Amazon Elastic Compute Cloud
User Guide for Linux (API Version 2014-06-15)
« 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.Did this page help you?  Yes | No |  Tell us about it...

IAM Roles for Amazon EC2

Applications must sign their API requests with AWS credentials. Therefore, if you are an application developer, you need a strategy for managing credentials for your applications that run on EC2 instances. For example, you can securely distribute your AWS credentials to the instances, enabling the applications on those instances to use your credentials to sign requests, while protecting them from other users. However, it's challenging to securely distribute credentials to each instance, especially those that AWS creates on your behalf, such as Spot Instances or instances in Auto Scaling groups. You must also be able to update the credentials on each instance when you rotate your AWS credentials.

We designed IAM roles so that your applications can securely make API requests from your instances, without requiring you to manage the security credentials that the applications use. Instead of creating and distributing your AWS credentials, you can delegate permission to make API requests using IAM roles as follows:

  1. Create an IAM role.

  2. Define which accounts or AWS services can assume the role.

  3. Define which API actions and resources the application can use after assuming the role.

  4. Specify the role when you launch your instances.

  5. Have the application retrieve a set of temporary credentials and use them.

For example, you can use IAM roles to grant permissions to applications running on your instances that needs to use a bucket in Amazon S3.

Note

Amazon EC2 uses an instance profile as a container for an IAM role. When you create an IAM role using the console, the console creates an instance profile automatically and gives it the same name as the role it corresponds to. If you use the AWS CLI, API, or an AWS SDK to create a role, you create the role and instance profile as separate actions, and you might give them different names. To launch an instance with an IAM role, you specify the name of its instance profile. When you launch an instance using the Amazon EC2 console, you can select a role to associate with the instance; however, the list that's displayed is actually a list of instance profile names. For more information, see Instance Profiles in the Using IAM.

You can specify permissions for IAM roles by creating a policy in JSON format. These are similar to the policies that you create for IAM users. If you make a change to a role, the change is propagated to all instances, simplifying credential management.

Note

You can't assign a role to an existing instance; you can only specify a role when you launch a new instance.

For more information about creating and using IAM roles, see Roles in the Using IAM guide.

Retrieving Security Credentials from Instance Metadata

An application on the instance retrieves the security credentials provided by the role from the instance metadata item iam/security-credentials/role-name. The application is granted the permissions for the actions and resources that you've defined for the role through the security credentials associated with the role. These security credentials are temporary and we rotate them automatically. We make new credentials available at least five minutes prior to the expiration of the old credentials.

Warning

If you use services that use instance metadata with IAM roles, ensure that you don't expose your credentials when the services make HTTP calls on your behalf. The types of services that could expose your credentials include HTTP proxies, HTML/CSS validator services, and XML processors that support XML inclusion.

The following command retrieves the security credentials for an IAM role named s3access.

$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access

The following is example output.

{
  "Code" : "Success",
  "LastUpdated" : "2012-04-26T16:39:16Z",
  "Type" : "AWS-HMAC",
  "AccessKeyId" : "AKIAIOSFODNN7EXAMPLE",
  "SecretAccessKey" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "Token" : "token",
  "Expiration" : "2012-04-27T22:39:16Z"
}

For more information about instance metadata, see Instance Metadata and User Data. For more information about temporary credentials, see the Using Temporary Security Credentials.

Granting an IAM User Permission to Launch an Instance with an IAM Role

To enable an IAM user to launch an instance with an IAM role, you must grant the user permission to pass the role to the instance.

For example, the following IAM policy grants users permission to launch an instance with the IAM role named s3access.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": "iam:PassRole",
        "Resource": "arn:aws:iam::123456789012:role/s3access"
    }]
}

Alternatively, you could grant IAM users access to all your roles by specifying the resource as "*" in this policy. However, consider whether users who launch instances with your roles (ones that exist or that you'll create later on) might be granted permissions that they don't need or shouldn't have.

For more information, see Permissions Required for Using Roles with Amazon EC2 in the Using IAM guide.

Launching an Instance with an IAM Role Using the Console

You must create an IAM role before you can launch an instance with that role.

Important

After you create an IAM role, it may take several seconds for the permissions to propagate. If your first attempt to launch an instance with a role fails, wait a few seconds before trying again. For more information, see Troubleshooting Working with Roles in the Using IAM guide.

To create an IAM role using the IAM console

  1. Open the IAM console.

  2. In the navigation pane, click Roles, and then click Create New Role.

  3. On the Set Role Name page, enter a name for the role and click Next Step.

  4. On the Select Role Type page, click Select next to Amazon EC2.

  5. On the Set Permissions page, specify the policies for the group. You can select a policy template or create custom policies. For example, for Amazon EC2, one of the following policy templates might meet your needs:

    • Power User Access

    • Read Only Access

    • Amazon EC2 Full Access

    • Amazon EC2 Read Only Access

    For more information about creating custom policies, see IAM Policies for Amazon EC2.

  6. On the second Set Permissions page, you can replace the automatically generated policy name with a name of your choice. Check the details in the policy document, and click Next Step.

  7. Review the role information, edit the role as needed, and then click Create Role.

To launch an instance with an IAM role

  1. Open the Amazon EC2 console.

  2. On the dashboard, click Launch Instance.

  3. Select an AMI, then select an instance type and click Next: Configure Instance Details.

  4. On the Configure Instance Details page, select the IAM role you created from the IAM role list.

    Note

    The IAM role list displays the name of the instance profile that you created when you created your IAM role. If you created your IAM role using the console, the instance profile was created for you and given the same name as the role. If you created your IAM role using the AWS CLI, API, or an AWS SDK, you may have named your instance profile differently.

  5. Configure any other details, then follow the instructions through the rest of the wizard, or click Review and Launch to accept default settings and go directly to the Review Instance Launch page.

  6. Review your settings, then click Launch to choose a key pair and launch your instance.

  7. If you are using the Amazon EC2 API actions in your application, retrieve the AWS security credentials made available on the instance and use them to sign the requests. Note that the AWS SDK does this for you.

    $ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name

Launching an Instance with an IAM Role Using the AWS CLI

You must create an IAM role before you can launch an instance with that role.

Important

After you create an IAM role, it may take several seconds for the permissions to propagate. If your first attempt to launch an instance with a role fails, wait a few seconds before trying again. For more information, see Troubleshooting Working with Roles in the Using IAM guide.

To create an IAM role using the AWS CLI

  • Create an IAM role with a policy that allows the role to use an Amazon S3 bucket.

    1. Create the following trust policy and save it in a text file named ec2-role-trust-policy.json.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": { "Service": "ec2.amazonaws.com"},
            "Action": "sts:AssumeRole"
          }
        ]
      }
    2. Create the s3access role. You'll specify the trust policy you created.

      $ aws iam create-role --role-name s3access --assume-role-policy-document file://ec2-role-trust-policy.json
      {
          "Role": {
              "AssumeRolePolicyDocument": {
                  "Version": "2012-10-17",
                  "Statement": [
                      {
                          "Action": "sts:AssumeRole",
                          "Effect": "Allow",
                          "Principal": {
                              "Service": "ec2.amazonaws.com"
                          }
                      }
                  ]
              },
              "RoleId": "AROAIIZKPBKS2LEXAMPLE",
              "CreateDate": "2013-12-12T23:46:37.247Z",
              "RoleName": "s3access",
              "Path": "/",
              "Arn": "arn:aws:iam::123456789012:role/s3access"
          }
      }
    3. Create an access policy and save it in a text file named ec2-role-access-policy.json. For example, this policy grants administrative permissions for Amazon S3 to applications running on the instance.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": ["s3:*"],
            "Resource": ["*"]
          }
        ]
      }
    4. Attach the access policy to the role.

      $ aws iam put-role-policy --role-name s3access --policy-name S3-Permissions --policy-document file://ec2-role-access-policy.json
      
    5. Create an instance profile named s3access-profile.

      $ aws iam create-instance-profile --instance-profile-name S3-Permissions
      {
          "InstanceProfile": {
              "InstanceProfileId": "AIPAJTLBPJLEGREXAMPLE",
              "Roles": [],
              "CreateDate": "2013-12-12T23:53:34.093Z",
              "InstanceProfileName": "S3-Permissions",
              "Path": "/",
              "Arn": "arn:aws:iam::123456789012:instance-profile/S3-Permissions"
          }
      }
    6. Add the s3access role to the s3access-profile instance profile.

      $ aws iam add-role-to-instance-profile --instance-profile-name S3-Permissions --role-name s3access

    For more information about these commands, see create-role, put-role-policy, and create-instance-profile in the AWS Command Line Interface Reference.

To launch an instance with an IAM role using the AWS CLI

  1. Launch an instance using the instance profile. The following example shows how to launch an instance with the instance profile.

    $ aws ec2 run-instances --image-id ami-11aa22bb --iam-instance-profile Name="S3-Permissions" --key-name my-key-pair --security-groups my-security-group --subnet-id subnet-1a2b3c4d

    For more information, see run-instances in the AWS Command Line Interface Reference.

  2. If you are using the Amazon EC2 API actions in your application, retrieve the AWS security credentials made available on the instance and use them to sign the requests. Note that the AWS SDK does this for you.

    $ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name

Launching an Instance with an IAM Role Using an AWS SDK

If you use an AWS SDK to write your application, you automatically get temporary security credentials from the role associated with the current instance. The AWS SDK documentation includes walkthroughs that show how an application can use security credentials from a IAM role to read an Amazon S3 bucket. For more information, see the following topics in the SDK documentation: