Getting started with Beanstalk Cluster

To create the cluster, node, and observability roles

1. Create a trust policy file for each service that assumes a role. The cluster role trusts Amazon EKS, the node role trusts Amazon EC2, and the observability role trusts Amazon EKS Pod Identity.

   $ cat > eks-trust.json <<'EOF'
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": {"Service": "eks.amazonaws.com"},
       "Action": "sts:AssumeRole"
     }]
   }
   EOF

   $ cat > ec2-trust.json <<'EOF'
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": {"Service": "ec2.amazonaws.com"},
       "Action": "sts:AssumeRole"
     }]
   }
   EOF

   $ cat > pods-trust.json <<'EOF'
   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": {"Service": "pods.eks.amazonaws.com"},
       "Action": ["sts:AssumeRole", "sts:TagSession"]
     }]
   }
   EOF

2. Create the cluster role and attach its policies.

   $ aws iam create-role \
       --role-name aws-elasticbeanstalk-eks-cluster-role \
       --assume-role-policy-document file://eks-trust.json
   $ for p in AmazonEKSClusterPolicy AmazonEKSNetworkingPolicy AmazonEKSComputePolicy \
            AmazonEKSBlockStoragePolicy AmazonEKSLoadBalancingPolicy AWSElasticBeanstalkEKSTagging; do
       aws iam attach-role-policy \
           --role-name aws-elasticbeanstalk-eks-cluster-role \
           --policy-arn arn:aws:iam::aws:policy/$p
   done

3. Create the node role and attach its policies.

   $ aws iam create-role \
       --role-name aws-elasticbeanstalk-eks-node-role \
       --assume-role-policy-document file://ec2-trust.json
   $ for p in AmazonEKSWorkerNodeMinimalPolicy AmazonEC2ContainerRegistryPullOnly \
            AmazonSSMManagedInstanceCore; do
       aws iam attach-role-policy \
           --role-name aws-elasticbeanstalk-eks-node-role \
           --policy-arn arn:aws:iam::aws:policy/$p
   done

4. Create the observability role and attach its policies.

   $ aws iam create-role \
       --role-name aws-elasticbeanstalk-eks-observability-role \
       --assume-role-policy-document file://pods-trust.json
   $ for p in CloudWatchAgentServerPolicy AWSElasticBeanstalkEKSObservability; do
       aws iam attach-role-policy \
           --role-name aws-elasticbeanstalk-eks-observability-role \
           --policy-arn arn:aws:iam::aws:policy/$p
   done

5. Record the three role ARNs. You pass them when you create the environment.

   $ for r in cluster node observability; do
       aws iam get-role --role-name aws-elasticbeanstalk-eks-$r-role \
           --query 'Role.Arn' --output text
   done

1. Create an Elastic Beanstalk application to contain the environment.

   $ aws elasticbeanstalk create-application \
       --application-name getting-started-cluster-app

2. Create the environment. The Cluster tier selects Beanstalk Cluster. Because this request has no version label, Elastic Beanstalk deploys the sample application.

   $ aws elasticbeanstalk create-environment \
       --application-name getting-started-cluster-app \
       --environment-name getting-started-cluster-env \
       --tier Name=Cluster,Type=EKS \
       --option-settings \
           Namespace=aws:elasticbeanstalk:eks,OptionName=cluster-role,Value=cluster-role-arn \
           Namespace=aws:elasticbeanstalk:eks,OptionName=node-role,Value=node-role-arn \
           Namespace=aws:elasticbeanstalk:eks:environment,OptionName=observability-role,Value=observability-role-arn

   Replace the role ARN placeholders with the roles that you prepared. The request omits service-port and load-balancer-type. Elastic Beanstalk resolves those settings to their defaults, 8080 and ALB. To choose different values, pass them with --option-settings. For the complete option reference, see Configuration options for Beanstalk Cluster environments.

3. Wait for the environment to become ready. A first environment can take 15 to 20 minutes while Elastic Beanstalk creates the Amazon EKS cluster and deploys the sample. The Amazon CLI provides a built-in waiter that polls until the environment reports Ready. The waiter polls at most 20 times at 20-second intervals, about 6 minutes 40 seconds, so on a first environment expect it to report Max attempts exceeded. Run it again until it reports success.

   $ aws elasticbeanstalk wait environment-exists \
       --environment-names getting-started-cluster-env

   The waiter reports Max attempts exceeded both when the environment is still being created and when creation has failed. If it does not report success after a few runs, inspect the environment's recent events and resolve the reported error before continuing.

   $ aws elasticbeanstalk describe-events \
       --environment-name getting-started-cluster-env \
       --query 'Events[].[EventDate,Severity,Message]' \
       --output table

4. Inspect the environment status, health color, health status, and URL.

   $ aws elasticbeanstalk describe-environments \
       --application-name getting-started-cluster-app \
       --environment-names getting-started-cluster-env \
       --query 'Environments[0].[Status,Health,HealthStatus,CNAME]' \
       --output table

   Confirm that the environment reports Ready and returns a nonempty CNAME. Open https:// followed by the CNAME in a web browser and confirm that the sample application responds. The load balancer answers on HTTPS only, so a request to http:// waits until it times out. To accept HTTP requests and have Elastic Beanstalk redirect them to HTTPS, see Configuring networking for Beanstalk Cluster environments. An idle environment can initially report Grey and NoData because it has received too few requests to determine application health; health events display this status as No Data. This does not indicate a failed deployment. After the application receives enough successful requests, health normally moves to Green and Ok. If the CNAME is empty, the application does not respond, or health reports a failure, inspect the environment's recent events before continuing:

   $ aws elasticbeanstalk describe-events \
       --environment-name getting-started-cluster-env \
       --query 'Events[].[EventDate,Severity,Message]' \
       --output table

   For the Cluster health model, see Monitoring Beanstalk Cluster environments.

1. Create an application version that points at your image.

   $ aws elasticbeanstalk create-application-version \
       --application-name getting-started-cluster-app \
       --version-label v1 \
       --image-configuration Source={Uri=your-image-uri}

   Replace your-image-uri with your image, for example 111122223333.dkr.ecr.us-east-1.amazonaws.com/my-app:v1. Because the image is already built, the version needs no build step and is ready to deploy.

2. Deploy the version to the environment.

   $ aws elasticbeanstalk update-environment \
       --environment-name getting-started-cluster-env \
       --version-label v1

3. Confirm that the deployment finished and the environment is serving your application.

   $ aws elasticbeanstalk describe-events \
       --environment-name getting-started-cluster-env \
       --query 'Events[].[EventDate,Severity,Message]' \
       --output table

   Open https:// followed by the environment's CNAME in a web browser and confirm that your application responds. If it doesn't, check the events for a deployment failure, and confirm that the image listens on the environment's service-port.

1. Terminate the environment.

   $ aws elasticbeanstalk terminate-environment \
       --environment-name getting-started-cluster-env

2. Wait for the environment to reach the Terminated status. The Amazon CLI provides a built-in waiter that polls until termination completes. This waiter has the same 20-attempt limit, so run it again until it reports success.

   $ aws elasticbeanstalk wait environment-terminated \
       --environment-names getting-started-cluster-env

   The waiter reports Max attempts exceeded both when termination is still in progress and when it has failed. If it does not report success after a few runs, resolve the error in the environment's events. Do not delete the application while the environment still exists.

3. Delete the application and its application versions, including the sample version that Elastic Beanstalk created and any version that you added. This does not delete a container image that you supplied or the repository that holds it; see Building container images for Beanstalk Cluster environments.

   $ aws elasticbeanstalk delete-application \
       --application-name getting-started-cluster-app