Attaching AWS IAM Roles To EC2 Instances

Overview

AWS Identity and Access Management (IAM) roles enable your applications running an Amazon EC2 instance to use temporary security credentials. IAM roles for EC2 make it easier for your applications to make API requests securely from an instance because they don't require you to manage AWS security credentials that the applications use. Recently, AWS enabled use of temporary security credentials for your applications by attaching an IAM role to an existing EC2 instance by using the AWS Console.

When you use a role, you don't have to distribute long-term credentials (such as a username and password or access keys) to an EC2 instance. Instead, the role supplies temporary permissions that applications can use when they make calls to other AWS resources. When you launch an EC2 instance, you specify an IAM role to associate with the instance. Applications that run on the instance can then use the role-supplied temporary credentials to sign API requests.

How roles work for EC2 instances

In the diagram below, an administrator runs an application on an EC2 instance that requires access to the S3 bucket named "Images". An administrator creates the "MatillionRole" service role and attaches the role to the EC2 instance. The role includes a permissions policy that grants read-only access to the specified S3 bucket. It also includes a trust policy that allows the EC2 instance to assume the role and retrieve the temporary credentials.

When the application runs on the instance, it can use the role's temporary credentials to access the "Image" bucket. The administrator doesn't have to grant the developer permission to access the images bucket, and the administrator never has to share or manage credentials.

You can attach an IAM role to an existing EC2 instance from the EC2 console. You can also use the EC2 console to replace an IAM role attached to an existing instance. This guide will give you an overview on how roles works for EC2 instances, how to create IAM roles, and how to attach an IAM role to an existing EC2 instance using the EC2 console and the AWS CLI.

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 change a role, the change is propagated to all instances.

When creating IAM roles, associate "least privilege" IAM policies that restrict access to the specific API calls the application requires.

Create an IAM role

You must create an IAM role before you can launch an instance with that role or attach it to an instance.

To create an IAM role using the IAM console

1. Sign in to the IAM console at https://console.aws.amazon.com/iam/. In the navigation pane, choose Roles and click Create role.
2. On the Create role page, Select "type of trusted entity" as AWS service. Select a service as EC2 from the list to view its use case, and then choose a "use case" as EC2 and click Next: Permissions.
3. On the Attach permissions policy page, select the Policy from the list of AWS managed policies that grants your instances access to the resources. If needed, you can create a new policy to attach and click Next:Tags.
4. On the IAM tags page, you can add "key-value" pairs that you can add to your role. Tags can include user information such as an email address, or can be descriptive, such as a job title. Click Next:Review.
5. On the Review page, enter a name for the role and click Create role.

Alternatively, you can use the AWS CLI to create an IAM role. The following example creates an IAM role with a policy that allows the role to use an Amazon S3 bucket.

To create an IAM role using the AWS CLI

Creating a role from the AWS CLI involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the AWS CLI you must explicitly perform each step yourself. You must create the role and then assign a permissions policy to the role. Optionally, you can also set the permissions boundary for your role.

1. Create the 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 MatillionRole role and specify the trust policy that you created using the aws iam create-role command.

aws iam create-role --role-name MatillionRole --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": "MatillionRole",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/MatillionRole"
}
}

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 using the AWS IAM put-role-policy command.

aws iam put-role-policy --role-name MatillionRole --policy-name S3-Permissions --policy-document file://ec2-role-access-policy.json

5. Add custom attributes to the role by attaching tags by using the tag-role command. It is an optional field.
6. Set the permissions boundary for the role using the AWS IAM put-role-permissions-boundary command.

Attach an IAM Role to a Matillion ETL instance

You can attach an IAM role to an existing EC2 instance from the EC2 console. You can also use the EC2 console to replace an IAM role attached to an existing instance.

To attach an IAM role to an instance that has no role, the instance can be in the "stopped" or "running" states.

To attach an IAM role to an instance using the IAM console

1. Sign in to the EC2 console at https://console.aws.amazon.com/ec2/. In the navigation pane, choose EC2 Dashboard and click instance.
2. Select the instance to which you want to attach an IAM role. To ensure an IAM role isn't already attached, verify that the value of the IAM role on the Description tab of the instance is empty.
3. From the Actions menu, choose Instance Settings → Attach/Replace IAM role.
4. On the Attach/Replace IAM role page, choose a role to attach (in this example, we choose MatillionRole) from the drop-down list.
5. Choose the role from the drop-down and click Apply.
6. The IAM role should now be attached to the EC2 instance.

To attach an IAM role to an instance using the AWS CLI

1. If required, describe your instances to get the ID of the instance to which to attach the role.

aws ec2 describe-instances

2. Use the associate-iam-instance-profile command to attach the IAM role to the instance by specifying the instance profile. You can use the Amazon Resource Name (ARN) of the instance profile, or you can use its name.

aws ec2 associate-iam-instance-profile --instance-id i-1234567890abcdef0 --iam-instance-profile Name="MatillionRole"

{
"IamInstanceProfileAssociation": {
"InstanceId": "i-1234567890abcdef0", 
"State": "associating", 
"AssociationId": "iip-assoc-0dbd8529a48294120", 
"IamInstanceProfile": {
"Id": "AIPAJLNLDX3AMYZNWYYAY", 
"Arn": "arn:aws:iam::123456789012:instance-profile/MatillionRole"
}
}
}