Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Permissions for Beanstalk Cluster

A Beanstalk Cluster environment does not use the Amazon Elastic Compute Cloud (Amazon EC2) instance profile from Beanstalk Standard. You provide the IAM roles that Amazon EKS requires for its cluster and nodes, and the role that Elastic Beanstalk uses to publish the environment's metrics, logs, and traces. You can optionally provide an application role for the running application. Elastic Beanstalk uses a service-linked role for its own operation of the environment.

Roles that you provide

A Beanstalk Cluster environment uses a cluster role, a node role, and an observability role. When you create an environment in the Elastic Beanstalk console and accept the default service access settings, the console creates all three for you, with the names in Name, trusted service, and permissions for each role, when they don't already exist in your account:

If you create these roles outside the Elastic Beanstalk console, we highly recommend that you create them exactly as specified in Name, trusted service, and permissions for each role. Then, when you create an environment, pass each role ARN in its configuration option. For a worked example, see Getting started with Beanstalk Cluster.

If you supply source for Elastic Beanstalk to build into a container image, you also provide an image build role. Amazon CodeBuild assumes it to run the build in your account. This role belongs to the application-version build rather than to the running environment. See Building container images for Beanstalk Cluster environments.

You can also provide an optional application role, which your running application uses to call Amazon services. See Application permissions.

Each role trusts a different service and carries its own permissions:

The subnet set alone selects the cluster, so use a different subnet set when you need a separate cluster with different infrastructure roles. You cannot change the subnets or the cluster, node, and observability roles of an existing Beanstalk Cluster environment. See Environment grouping. The optional application role is specific to an environment and can differ between environments; see Configure an application role.

Permissions to create the environment

Because you hand these roles to Elastic Beanstalk, the principal that creates the environment needs permission to pass them. Elastic Beanstalk verifies this before it provisions anything, so grant the following to that principal:

The following policy grants all of this. Replace the account ID with your own, use your application role's name, and remove any role that you don't pass. The role names shown are the ones in the preceding table, which the console creates and selects.

Unlike the console, which selects a role by name, a policy matches a role by its full ARN, so each Resource entry has to include the role's IAM path. The roles that the console creates sit at /service-role/, as shown here. If you created a role another way it might have no path, in which case its ARN is arn:aws:iam::111122223333:role/role-name. To read a role's ARN, run aws iam get-role --role-name role-name --query Role.Arn --output text.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InspectTheRoles",
      "Effect": "Allow",
      "Action": "iam:GetRole",
      "Resource": [
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-cluster-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-node-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-observability-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-image-build-role",
        "arn:aws:iam::111122223333:role/my-application-role"
      ]
    },
    {
      "Sid": "PassTheRolesToBeanstalk",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": [
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-cluster-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-node-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-observability-role",
        "arn:aws:iam::111122223333:role/service-role/aws-elasticbeanstalk-eks-image-build-role",
        "arn:aws:iam::111122223333:role/my-application-role"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": [
            "eks.amazonaws.com",
            "ec2.amazonaws.com",
            "pods.eks.amazonaws.com",
            "codebuild.amazonaws.com",
            "elasticbeanstalk.amazonaws.com"
          ]
        }
      }
    },
    {
      "Sid": "CreateServiceLinkedRolesOnFirstEnvironment",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::111122223333:role/aws-service-role/*",
      "Condition": {
        "StringEquals": {
          "iam:AWSServiceName": [
            "elasticbeanstalk.amazonaws.com",
            "eks.amazonaws.com"
          ]
        }
      }
    }
  ]
}

iam:GetRole is in its own statement because the iam:PassedToService condition key exists only in a PassRole request. Applying it to iam:GetRole in the same statement would prevent that permission from being granted at all.

This policy covers passing the roles only. It doesn't grant the Elastic Beanstalk actions that creating an application and an environment require.

Without these permissions, CreateEnvironment fails with an AccessDenied error naming the action it could not perform. For more information, see Grant a principal permission to pass a role to an Amazon service and CreateEnvironment.

Roles that Elastic Beanstalk manages

Elastic Beanstalk operates a Beanstalk Cluster environment through the AWSServiceRoleForElasticBeanstalk service-linked role, which it creates in your account. You do not create, configure, or pass this role. Amazon EKS likewise uses its own service-linked role, AWSServiceRoleForAmazonEKS. For how Elastic Beanstalk uses service-linked roles, see Using service-linked roles for Elastic Beanstalk.

Confirm the roles that the environment uses

After the environment reaches the Ready state, read its resolved configuration:

$ aws elasticbeanstalk describe-configuration-settings \
    --application-name my-app \
    --environment-name my-cluster-env \
    --query "ConfigurationSettings[0].OptionSettings[?OptionName=='cluster-role' || OptionName=='node-role' || OptionName=='observability-role'].[Namespace,OptionName,Value]" \
    --output table

Confirm that the cluster, node, and observability role entries contain the ARNs supplied during creation. If the environment uses an application role, run the credential-identity check in Configure an application role and confirm that the returned ARN identifies the selected role. For a source-based application version, wait for the version to report PROCESSED; that state confirms that Amazon CodeBuild could use the build role and complete the image build. See Building container images for Beanstalk Cluster environments.

Application permissions

Use an application role when the running application must call Amazon services. Configure the role before creating the environment and grant only the permissions required by the application. The application receives the role through Amazon EKS Pod Identity rather than through an Amazon EC2 instance profile.

Pass the role's ARN in the application-role setting of the aws:elasticbeanstalk:eks:environment namespace, or select the role in the Elastic Beanstalk console when you create the environment.

The application role is also the role that reads the credentials for a third-party observability backend. If you set any observability backend to custom, grant the application role secretsmanager:GetSecretValue and secretsmanager:DescribeSecret on the Secrets Manager secret named by custom-credentials. See Sending observability data to a third-party backend.

Configure an application role

Create the application role before you create the environment. Grant the role only the actions and resources that the application requires. Configure its trust policy for Amazon EKS Pod Identity, including sts:AssumeRole and sts:TagSession for the pods.eks.amazonaws.com service principal:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

If the application receives AccessDenied, verify that you selected the intended role during environment creation, that its trust policy allows Amazon EKS Pod Identity, and that its identity-based policy permits the requested action and resource. Correct the trust or permissions policy and repeat both the credential-identity check and the application service call. If the wrong role was selected, create a replacement environment with the intended role instead of adding application permissions to the wrong role. Use separate application roles when environments require different access. Do not grant application permissions to the cluster or node role.

Diagnose role failures

Start with the Elastic Beanstalk events for the environment. Set operation_start to the timestamp recorded immediately before the failed request:

$ operation_start='timestamp-recorded-before-the-request'
$ aws elasticbeanstalk describe-events \
    --environment-name my-cluster-env \
    --severity ERROR \
    --start-time "$operation_start" \
    --max-items 20