openshift-docs/modules/installation-creating-aws-bootstrap.adoc

// Module included in the following assemblies:
//
// * installing/installing_aws/installing-aws-user-infra.adoc
// * installing/installing_aws/installing-restricted-networks-aws.adoc

:_mod-docs-content-type: PROCEDURE
[id="installation-creating-aws-bootstrap_{context}"]
= Creating the bootstrap node in AWS

You must create the bootstrap node in Amazon Web Services (AWS) to use during {product-title} cluster initialization. You do this by:

* Providing a location to serve the `bootstrap.ign` Ignition config file to your cluster. This file is located in your installation directory. The provided CloudFormation Template assumes that the Ignition config files for your cluster are served from an S3 bucket. If you choose to serve the files from another location, you must modify the templates.
* Using the provided CloudFormation template and a custom parameter file to create a stack of AWS resources. The stack represents the bootstrap node that your {product-title} installation requires.

[NOTE]
====
If you do not use the provided CloudFormation template to create your bootstrap
node, you must review the provided information and manually create
the infrastructure. If your cluster does not initialize correctly, you might
have to contact Red Hat support with your installation logs.
====

.Prerequisites

* You configured an AWS account.
* You added your AWS keys and region to your local AWS profile by running `aws configure`.
* You generated the Ignition config files for your cluster.
* You created and configured a VPC and associated subnets in AWS.
* You created and configured DNS, load balancers, and listeners in AWS.
* You created the security groups and roles required for your cluster in AWS.

.Procedure

. Create the bucket by running the following command:
+
[source,terminal]
----
$ aws s3 mb s3://<cluster-name>-infra <1>
----
<1> `<cluster-name>-infra` is the bucket name. When creating the `install-config.yaml` file, replace `<cluster-name>` with the name specified for the cluster.
+
You must use a presigned URL for your S3 bucket, instead of the `s3://` schema, if you are:
** Deploying to a region that has endpoints that differ from the AWS SDK.
** Deploying a proxy.
** Providing your own custom endpoints.

. Upload the `bootstrap.ign` Ignition config file to the bucket by running the following command:
+
[source,terminal]
----
$ aws s3 cp <installation_directory>/bootstrap.ign s3://<cluster-name>-infra/bootstrap.ign <1>
----
<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in.

. Verify that the file uploaded by running the following command:
+
[source,terminal]
----
$ aws s3 ls s3://<cluster-name>-infra/
----
+
.Example output
[source,terminal]
----
2019-04-03 16:15:16     314878 bootstrap.ign
----
+
[NOTE]
====
The bootstrap Ignition config file does contain secrets, like X.509 keys. The following steps provide basic security for the S3 bucket. To provide additional security, you can enable an S3 bucket policy to allow only certain users, such as the OpenShift IAM user, to access objects that the bucket contains. You can avoid S3 entirely and serve your bootstrap Ignition config file from any address that the bootstrap machine can reach.
====

. Create a JSON file that contains the parameter values that the template requires:
+
[source,json]
----
[
  {
    "ParameterKey": "InfrastructureName", <1>
    "ParameterValue": "mycluster-<random_string>" <2>
  },
  {
    "ParameterKey": "RhcosAmi", <3>
    "ParameterValue": "ami-<random_string>" <4>
  },
  {
    "ParameterKey": "AllowedBootstrapSshCidr", <5>
    "ParameterValue": "0.0.0.0/0" <6>
  },
  {
    "ParameterKey": "PublicSubnet", <7>
    "ParameterValue": "subnet-<random_string>" <8>
  },
  {
    "ParameterKey": "MasterSecurityGroupId", <9>
    "ParameterValue": "sg-<random_string>" <10>
  },
  {
    "ParameterKey": "VpcId", <11>
    "ParameterValue": "vpc-<random_string>" <12>
  },
  {
    "ParameterKey": "BootstrapIgnitionLocation", <13>
    "ParameterValue": "s3://<bucket_name>/bootstrap.ign" <14>
  },
  {
    "ParameterKey": "AutoRegisterELB", <15>
    "ParameterValue": "yes" <16>
  },
  {
    "ParameterKey": "RegisterNlbIpTargetsLambdaArn", <17>
    "ParameterValue": "arn:aws:lambda:<aws_region>:<account_number>:function:<dns_stack_name>-RegisterNlbIpTargets-<random_string>" <18>
  },
  {
    "ParameterKey": "ExternalApiTargetGroupArn", <19>
    "ParameterValue": "arn:aws:elasticloadbalancing:<aws_region>:<account_number>:targetgroup/<dns_stack_name>-Exter-<random_string>" <20>
  },
  {
    "ParameterKey": "InternalApiTargetGroupArn", <21>
    "ParameterValue": "arn:aws:elasticloadbalancing:<aws_region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <22>
  },
  {
    "ParameterKey": "InternalServiceTargetGroupArn", <23>
    "ParameterValue": "arn:aws:elasticloadbalancing:<aws_region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <24>
  }
]

----
<1> The name for your cluster infrastructure that is encoded in your Ignition
config files for the cluster.
<2> Specify the infrastructure name that you extracted from the Ignition config
file metadata, which has the format `<cluster-name>-<random-string>`.
<3> Current {op-system-first} AMI to use for the bootstrap node based on your selected architecture.
<4> Specify a valid `AWS::EC2::Image::Id` value.
<5> CIDR block to allow SSH access to the bootstrap node.
<6> Specify a CIDR block in the format `x.x.x.x/16-24`.
<7> The public subnet that is associated with your VPC to launch the bootstrap
node into.
<8> Specify the `PublicSubnetIds` value from the output of the CloudFormation
template for the VPC.
<9> The master security group ID (for registering temporary rules)
<10> Specify the `MasterSecurityGroupId` value from the output of the
CloudFormation template for the security group and roles.
<11> The VPC created resources will belong to.
<12> Specify the `VpcId` value from the output of the CloudFormation template
for the VPC.
<13> Location to fetch bootstrap Ignition config file from.
<14> Specify the S3 bucket and file name in the form
`s3://<bucket_name>/bootstrap.ign`.
<15> Whether or not to register a network load balancer (NLB).
<16> Specify `yes` or `no`. If you specify `yes`, you must provide a Lambda
Amazon Resource Name (ARN) value.
<17> The ARN for NLB IP target registration lambda group.
<18> Specify the `RegisterNlbIpTargetsLambda` value from the output of the
CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if
deploying the cluster to an AWS GovCloud region.
<19> The ARN for external API load balancer target group.
<20> Specify the `ExternalApiTargetGroupArn` value from the output of the
CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if
deploying the cluster to an AWS GovCloud region.
<21> The ARN for internal API load balancer target group.
<22> Specify the `InternalApiTargetGroupArn` value from the output of the
CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if
deploying the cluster to an AWS GovCloud region.
<23> The ARN for internal service load balancer target group.
<24> Specify the `InternalServiceTargetGroupArn` value from the output of the
CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if
deploying the cluster to an AWS GovCloud region.

. Copy the template from the *CloudFormation template for the bootstrap machine*
section of this topic and save it as a YAML file on your computer. This template
describes the bootstrap machine that your cluster requires.

. Optional: If you are deploying the cluster with a proxy, you must update the ignition in the template to add the  `ignition.config.proxy` fields. Additionally, If you have added the Amazon EC2, Elastic Load Balancing, and S3 VPC endpoints to your VPC, you must add these endpoints to the `noProxy` field.

. Launch the CloudFormation template to create a stack of AWS resources that represent the bootstrap node:
+
[IMPORTANT]
====
You must enter the command on a single line.
====
+
[source,terminal]
----
$ aws cloudformation create-stack --stack-name <name> <1>
     --template-body file://<template>.yaml <2>
     --parameters file://<parameters>.json <3>
     --capabilities CAPABILITY_NAMED_IAM <4>
----
<1> `<name>` is the name for the CloudFormation stack, such as `cluster-bootstrap`.
You need the name of this stack if you remove the cluster.
<2> `<template>` is the relative path to and name of the CloudFormation template
YAML file that you saved.
<3> `<parameters>` is the relative path to and name of the CloudFormation
parameters JSON file.
<4> You must explicitly declare the `CAPABILITY_NAMED_IAM` capability because the provided template creates some `AWS::IAM::Role` and `AWS::IAM::InstanceProfile` resources.
+
.Example output
[source,terminal]
----
arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-bootstrap/12944486-2add-11eb-9dee-12dace8e3a83
----

. Confirm that the template components exist:
+
[source,terminal]
----
$ aws cloudformation describe-stacks --stack-name <name>
----
+
After the `StackStatus` displays `CREATE_COMPLETE`, the output displays values
for the following parameters. You must provide these parameter values to
the other CloudFormation templates that you run to create your cluster:
[horizontal]
`BootstrapInstanceId`:: The bootstrap Instance ID.
`BootstrapPublicIp`:: The bootstrap node public IP address.
`BootstrapPrivateIp`:: The bootstrap node private IP address.