AWS Elastic Beanstalk
Developer Guide (last updated: 12 December, 2014) (API Version 2010-12-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Using IAM Roles with AWS Elastic Beanstalk

IAM roles control what actions and AWS services your Elastic Beanstalk application can access. With roles, you don't have to share long-term credentials or define permissions for each entity that requires access to a resource. To allow your application access to AWS resources, you attach a custom action policy to the IAM role and use the instance profile associated with that role to launch your Amazon EC2 instances. Examples of when Elastic Beanstalk uses IAM roles include when your application requires access to AWS resources such as DynamoDB or if you want Elastic Beanstalk to rotate your logs to Amazon S3.

This document describes how to configure your AWS Elastic Beanstalk application to access AWS services using IAM roles. For more information about using IAM roles with temporary security credentials to access the AWS Elastic Beanstalk API, see Creating Temporary Security Credentials for Delegating API Access in the AWS Security Token Service User Guide.

You can use IAM roles with any of the following container types (unless they are designated as legacy):

  • Docker

  • Node.js

  • PHP 5.3, PHP 5.4, and PHP 5.5

  • Python

  • Ruby 1.8.7, 1.9.3, 2.0.0, and 2.1.2

  • Apache Tomcat 6 and 7

  • Windows Server 2008 R2 running IIS 7.5 and Windows Server 2012 running IIS 8

AWS Elastic Beanstalk supports legacy and nonlegacy containers for PHP 5.3, Windows Server 2008 R2 running IIS 7.5, Windows Server 2012 running IIS 8, and Apache Tomcat 6 or 7. If you are not sure if you are using a legacy container, check the Elastic Beanstalk console. For instructions, see To check if you are using a legacy container type.

For an overview of the steps required to grant permissions to applications running in AWS Elastic Beanstalk using IAM roles, see Granting Permissions to Users and Services Using IAM Roles.

The following sections provides examples for using IAM roles with AWS Elastic Beanstalk, including sample action policies.

Granting IAM Users Permissions to Create and Pass IAM Roles

You need to have the appropriate permissions so that AWS Elastic Beanstalk can create a default role and instance profile for you, or to view the list of instance profiles available in your environment. If you tried to create or update your environment to use an instance profile, but you received an error, the error might have occurred because you do not have the correct permissions. Your account administrator should allow the following actions:

"iam:AddRoleToInstanceProfile",
"iam:CreateInstanceProfile",
"iam:CreateRole",
"iam:PassRole",
"iam:ListInstanceProfiles"

You require the create role, create instance profile, and add to instance profile actions in order to create a role. The list instance profiles actions allows you to list the instance profiles in the AWS account, and the pass role action allows you to associate a role to an environment.

The following example shows one statement that gives a broad set of permissions to AWS products that AWS Elastic Beanstalk uses to manage applications and environments and includes permissions to create an instance profile and view a list of available instance profiles.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticbeanstalk:*",
        "ec2:*",
        "elasticloadbalancing:*",
        "autoscaling:*",
        "cloudwatch:*",
        "s3:*",
        "sns:*",
        "cloudformation:*",
        "rds:*",
        "iam:AddRoleToInstanceProfile",
        "iam:CreateInstanceProfile",
        "iam:CreateRole",
        "iam:PassRole",
        "iam:ListInstanceProfiles"
      ],
      "Resource": "*"
    }
  ]
}        		

Granting IAM Role Permissions for Worker Environment Tiers

The following example statement gives permissions to the IAM role in your instance profile to run the aws-sqsd daemon in the worker environment tier and publish metrics to CloudWatch.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "QueueAccess",
      "Action": [
        "sqs:ChangeMessageVisibility",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "MetricsAccess",
      "Action": [
        "cloudwatch:PutMetricData"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}        		

If you are using a different account with an unmanaged Amazon SQS queue, you must also edit the policy on the queue to grant access to the queue to other accounts, such as the one that you use with the worker tier. For an example statement, see Example: Using a resource-based policy to delegate access to an Amazon SQS queue in another account in the AWS Identity and Access Management User Guide.

Granting IAM Role Permissions to Access an Amazon S3 Bucket

The following example policy grants read-only permission to the IAM role with the role name "janedoe" to the Amazon S3 bucket "my-bucket".

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3ReadOnlyPerms",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/janedoe"
      },
      "Action": [
        "s3:ListBucketVersions",
        "s3:GetObjectVersion",
        "s3:ListBucket",
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::my-bucket/*",
        "arn:aws:s3:::my-bucket"
      ]
    }
  ]
}