Menu
AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)

Using Service-Linked Roles for Elastic Beanstalk

AWS Elastic Beanstalk can use AWS Identity and Access Management (IAM) service-linked roles. A service-linked role is a unique type of IAM role that is linked directly to Elastic Beanstalk. Service-linked roles are predefined by Elastic Beanstalk and include all the permissions that the service requires to call other AWS services on your behalf. Elastic Beanstalk uses a service-linked role when you create an environment and don't explicitly specify a service role for it.

A service-linked role makes setting up Elastic Beanstalk easier because you don’t have to manually add the necessary permissions. Elastic Beanstalk defines the permissions of its service-linked roles, and unless defined otherwise, only Elastic Beanstalk can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity.

You can delete the roles only after first deleting their related resources. This protects your Elastic Beanstalk resources because you can't inadvertently remove permission to access the resources.

For information about other services that support service-linked roles, see AWS Services That Work with IAM and look for the services that have Yes in the Service-Linked Role column. Choose a Yes with a link to view the service-linked role documentation for that service.

Service-Linked Role Permissions for Elastic Beanstalk

Elastic Beanstalk uses the service-linked role named AWSServiceRoleForElasticBeanstalk. Elastic Beanstalk uses this service-linked role to call other AWS services on your behalf.

The AWSServiceRoleForElasticBeanstalk service-linked role trusts the elasticbeanstalk.amazonaws.com service to assume the role.

The permissions policy of the AWSServiceRoleForElasticBeanstalk service-linked role contains all of the permissions that Elastic Beanstalk needs to complete actions on your behalf:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowPassRoleToElasticBeanstalk", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "*", "Condition": { "StringLikeIfExists": { "iam:PassedToService": "elasticbeanstalk.amazonaws.com" } } }, { "Sid": "AllowCloudformationOperationsOnElasticBeanstalkStacks", "Effect": "Allow", "Action": [ "cloudformation:*" ], "Resource": [ "arn:aws:cloudformation:*:*:stack/awseb-*", "arn:aws:cloudformation:*:*:stack/eb-*" ] }, { "Sid": "AllowDeleteCloudwatchLogGroups", "Effect": "Allow", "Action": [ "logs:DeleteLogGroup" ], "Resource": [ "arn:aws:logs:*:*:log-group:/aws/elasticbeanstalk*" ] }, { "Sid": "AllowS3OperationsOnElasticBeanstalkBuckets", "Effect": "Allow", "Action": [ "s3:*" ], "Resource": [ "arn:aws:s3:::elasticbeanstalk-*", "arn:aws:s3:::elasticbeanstalk-*/*" ] }, { "Sid": "AllowOperations", "Effect": "Allow", "Action": [ "autoscaling:AttachInstances", "autoscaling:CreateAutoScalingGroup", "autoscaling:CreateLaunchConfiguration", "autoscaling:DeleteLaunchConfiguration", "autoscaling:DeleteAutoScalingGroup", "autoscaling:DeleteScheduledAction", "autoscaling:DescribeAccountLimits", "autoscaling:DescribeAutoScalingGroups", "autoscaling:DescribeAutoScalingInstances", "autoscaling:DescribeLaunchConfigurations", "autoscaling:DescribeLoadBalancers", "autoscaling:DescribeNotificationConfigurations", "autoscaling:DescribeScalingActivities", "autoscaling:DescribeScheduledActions", "autoscaling:DetachInstances", "autoscaling:PutScheduledUpdateGroupAction", "autoscaling:ResumeProcesses", "autoscaling:SetDesiredCapacity", "autoscaling:SuspendProcesses", "autoscaling:TerminateInstanceInAutoScalingGroup", "autoscaling:UpdateAutoScalingGroup", "cloudwatch:PutMetricAlarm", "ec2:AssociateAddress", "ec2:AllocateAddress", "ec2:AuthorizeSecurityGroupEgress", "ec2:AuthorizeSecurityGroupIngress", "ec2:CreateSecurityGroup", "ec2:DeleteSecurityGroup", "ec2:DescribeAccountAttributes", "ec2:DescribeAddresses", "ec2:DescribeImages", "ec2:DescribeInstances", "ec2:DescribeKeyPairs", "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeVpcs", "ec2:DisassociateAddress", "ec2:ReleaseAddress", "ec2:RevokeSecurityGroupEgress", "ec2:RevokeSecurityGroupIngress", "ec2:TerminateInstances", "ecs:CreateCluster", "ecs:DeleteCluster", "ecs:DescribeClusters", "ecs:RegisterTaskDefinition", "elasticbeanstalk:*", "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", "elasticloadbalancing:ConfigureHealthCheck", "elasticloadbalancing:CreateLoadBalancer", "elasticloadbalancing:DeleteLoadBalancer", "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", "elasticloadbalancing:DescribeInstanceHealth", "elasticloadbalancing:DescribeLoadBalancers", "elasticloadbalancing:DescribeTargetHealth", "elasticloadbalancing:RegisterInstancesWithLoadBalancer", "elasticloadbalancing:DescribeTargetGroups", "elasticloadbalancing:RegisterTargets", "elasticloadbalancing:DeregisterTargets", "iam:ListRoles", "logs:CreateLogGroup", "logs:PutRetentionPolicy", "rds:DescribeDBInstances", "rds:DescribeOrderableDBInstanceOptions", "rds:DescribeDBEngineVersions", "sns:ListTopics", "sns:GetTopicAttributes", "sns:ListSubscriptionsByTopic", "sqs:GetQueueAttributes", "sqs:GetQueueUrl", "codebuild:CreateProject", "codebuild:DeleteProject", "codebuild:BatchGetBuilds", "codebuild:StartBuild" ], "Resource": [ "*" ] } ] }

You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role.

To allow an IAM entity to create the AWSServiceRoleForElasticBeanstalk service-linked role

Add the following statement to the permissions policy for the IAM entity that needs to create the service-linked role:

Copy
{ "Effect": "Allow", "Action": [ "iam:CreateServiceLinkedRole", "iam:PutRolePolicy" ], "Resource": "arn:aws:iam::*:role/aws-service-role/elasticbeanstalk.amazonaws.com/AWSServiceRoleForElasticBeanstalk*", "Condition": {"StringLike": {"iam:AWSServiceName": "elasticbeanstalk.amazonaws.com"}} }

To allow an IAM entity to edit the description of the AWSServiceRoleForElasticBeanstalk service-linked role

Add the following statement to the permissions policy for the IAM entity that needs to edit the description of a service-linked role:

Copy
{ "Effect": "Allow", "Action": [ "iam:UpdateRoleDescription" ], "Resource": "arn:aws:iam::*:role/aws-service-role/elasticbeanstalk.amazonaws.com/AWSServiceRoleForElasticBeanstalk*", "Condition": {"StringLike": {"iam:AWSServiceName": "elasticbeanstalk.amazonaws.com"}} }

To allow an IAM entity to delete the AWSServiceRoleForElasticBeanstalk service-linked role

Add the following statement to the permissions policy for the IAM entity that needs to delete a service-linked role:

Copy
{ "Effect": "Allow", "Action": [ "iam:DeleteServiceLinkedRole", "iam:GetServiceLinkedRoleDeletionStatus" ], "Resource": "arn:aws:iam::*:role/aws-service-role/elasticbeanstalk.amazonaws.com/AWSServiceRoleForElasticBeanstalk*", "Condition": {"StringLike": {"iam:AWSServiceName": "elasticbeanstalk.amazonaws.com"}} }

Alternatively, you can use an AWS managed policy to provide full access to Elastic Beanstalk.

Creating a Service-Linked Role for Elastic Beanstalk

You don't need to manually create the AWSServiceRoleForElasticBeanstalk role. When you create an Elastic Beanstalk environment using the Elastic Beanstalk API and don't specify a service role, Elastic Beanstalk creates the service-linked role for you.

You can also use the IAM console, the AWS CLI, or the IAM API to create a service-linked role using the Elastic Beanstalk use case. For more information, see Creating a Service-Linked Role in the IAM User Guide.

Important

If you were using the Elastic Beanstalk service before September 27, 2017, when it began supporting service-linked roles, Elastic Beanstalk created the AWSServiceRoleForElasticBeanstalk role in your account. To learn more, see A New Role Appeared in My IAM Account.

Editing a Service-Linked Role for Elastic Beanstalk

Elastic Beanstalk does not allow you to edit the AWSServiceRoleForElasticBeanstalk service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM.

Editing a Service-Linked Role Description (IAM Console)

You can use the IAM console to edit the description of a service-linked role.

To edit the description of a service-linked role (console)

  1. In the navigation pane of the IAM console, choose Roles.

  2. Choose the name of the role to modify.

  3. To the far right of Role description, choose Edit.

  4. Type a new description in the box, and then choose Save.

Editing a Service-Linked Role Description (IAM CLI)

You can use IAM commands from the AWS Command Line Interface to edit the description of a service-linked role.

To change the description of a service-linked role (CLI)

  1. (Optional) To view the current description for a role, use the following commands:

    Copy
    $ aws iam get-role --role-name role-name

    Use the role name, not the ARN, to refer to roles with the CLI commands. For example, if a role has the following ARN: arn:aws:iam::123456789012:role/myrole, you refer to the role as myrole.

  2. To update a service-linked role's description, use one of the following commands:

    Copy
    $ aws iam update-role-description --role-name role-name --description description

Editing a Service-Linked Role Description (IAM API)

You can use the IAM API to edit the description of a service-linked role.

To change the description of a service-linked role (API)

  1. (Optional) To view the current description for a role, use the following command:

    IAM API: GetRole

  2. To update a role's description, use the following command:

    IAM API: UpdateRoleDescription

Deleting a Service-Linked Role for Elastic Beanstalk

If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or maintained. However, you must clean up your service-linked role before you can delete it.

Cleaning up a Service-Linked Role

Before you can use IAM to delete a service-linked role, you must first confirm that the role has no active sessions and remove any resources used by the role.

To check whether the service-linked role has an active session in the IAM console

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane of the IAM console, choose Roles. Then choose the name (not the check box) of the AWSServiceRoleForElasticBeanstalk role.

  3. On the Summary page for the selected role, choose the Access Advisor tab.

  4. On the Access Advisor tab, review recent activity for the service-linked role.

    Note

    If you are unsure whether Elastic Beanstalk is using the AWSServiceRoleForElasticBeanstalk role, you can try to delete the role. If the service is using the role, the deletion fails and you can view the regions where the role is being used. If the role is being used, you must wait for the session to end before you can delete the role. You cannot revoke the session for a service-linked role.

When you find out which Elastic Beanstalk environments are using the AWSServiceRoleForElasticBeanstalk role, you can terminate them, and then delete the role.

To terminate an Elastic Beanstalk environment (console)

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Actions, and then choose Terminate Environment.

  4. In the Confirm Termination dialog box, type the environment name, and then choose Terminate.

See eb terminate for details about terminating an Elastic Beanstalk environment using the EB CLI.

See TerminateEnvironment for details about terminating an Elastic Beanstalk environment using the API.

Deleting a Service-Linked Role

You can use the IAM console, the AWS CLI, or the IAM API to delete a service-linked role. For more information, see Deleting a Service-Linked Role in the IAM User Guide.