Create an IAM role and policy Permissions required for ECS Exec Amazon EC2 instances additional configuration External instance additional configuration

Amazon ECS task role

Your Amazon ECS tasks can have an IAM role associated with them. The permissions granted in the IAM role are assumed by the containers running in the task. This role allows your application code (on the container) to use other AWS services. The task role is required when your application accesses other AWS services, such as Amazon S3. For the IAM permissions that Amazon ECS needs to pull container images and run the task, see Amazon ECS task execution IAM role.

The following are the benefits of using task roles:

Credential Isolation: A container can only retrieve credentials for the IAM role that is defined in the task definition to which it belongs; a container never has access to credentials that are intended for another container that belongs to another task.
Authorization: Unauthorized containers cannot access IAM role credentials defined for other tasks.
Auditing: Access and event logging is available through CloudTrail to ensure retrospective auditing. Task credentials have a context of taskArn that is attached to the session, so CloudTrail logs show which task is using which role.

Note

When you specify an IAM role for a task, the AWS CLI or other SDKs in the containers for that task use the AWS credentials provided by the task role exclusively and they no longer inherit any IAM permissions from the Amazon EC2 or external instance they are running on.

Create an IAM role and policy

When creating an IAM policy for your tasks to use, the policy must include the permissions that you want the containers in your tasks to assume. You can use an existing AWS managed policy, or you can create a custom policy from scratch that meets your specific needs. For more information, see Creating IAM policies in the IAM User Guide.

Important

For Amazon ECS tasks (for all launch types), we recommend that you use the IAM policy and role for your tasks. These credentials allow your task to make AWS API requests without calling sts:AssumeRole to assume the same role that is already associated with the task. If your task requires that a role assumes itself, you must create a trust policy that explicitly allows that role to assume itself. For more information, see Modifying a role trust policy in the IAM User Guide.

After the IAM policy is created, you can create an IAM role which includes that policy which you reference in your Amazon ECS task definition. You can create the role using the Elastic Container Service Task use case in the IAM console. Then, you can attach your specific IAM policy to the role that gives the containers in your task the permissions you desire. The procedures below describe how to do this.

If you have multiple task definitions or services that require IAM permissions, you should consider creating a role for each specific task definition or service with the minimum required permissions for the tasks to operate so that you can minimize the access that you provide for each task.

For information about the service endpoint for your Region, see Service endpoints in the Amazon Web Services General Reference Guide.

The IAM task role must have a trust policy that specifies the ecs-tasks.amazonaws.com service. The sts:AssumeRole permission allows your tasks to assume an IAM role that's different from the one that the Amazon EC2 instance uses. This way, your task doesn't inherit the role associated with the Amazon EC2 instance. The following is an example trust policy. Replace the Region identifier and specify the AWS account number that you use when launching tasks.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Service":[
               "ecs-tasks.amazonaws.com"
            ]
         },
         "Action":"sts:AssumeRole",
         "Condition":{
            "ArnLike":{
            "aws:SourceArn":"arn:aws:ecs:us-west-2:111122223333:*"
            },
            "StringEquals":{
               "aws:SourceAccount":"111122223333"
            }
         }
      }
   ]
}

Important

When creating your task IAM role, it is recommended that you use the aws:SourceAccount or aws:SourceArn condition keys in either the trust relationship or the IAM policy associated with the role to scope the permissions further to prevent the confused deputy security issue. Using the aws:SourceArn condition key to specify a specific cluster is not currently supported, you should use the wildcard to specify all clusters. To learn more about the confused deputy problem and how to protect your AWS account, see The confused deputy problem in the IAM User Guide.

The following procedures describe how to create a policy to retrieve objects from Amazon S3 with an example policy. Replace all user input with your own values.

AWS Management Console

To use the JSON policy editor to create a policy

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane on the left, choose Policies.

If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose Get Started.
At the top of the page, choose Create policy.
In the Policy editor section, choose the JSON option.

Enter the following JSON policy document:


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetObject"
         ],
         "Resource":[
            "arn:aws:s3:::my-task-secrets-bucket/*"
         ],
         "Condition":{
            "ArnLike":{
            "aws:SourceArn":"arn:aws:ecs:region:123456789012:*"
            },
            "StringEquals":{
               "aws:SourceAccount":"123456789012"
            }
         }
      }
   ]
}

Choose Next.

Note
You can switch between the Visual and JSON editor options anytime. However, if you make changes or choose Next in the Visual editor, IAM might restructure your policy to optimize it for the visual editor. For more information, see Policy restructuring in the IAM User Guide.
On the Review and create page, enter a Policy name and a Description (optional) for the policy that you are creating. Review Permissions defined in this policy to see the permissions that are granted by your policy.
Choose Create policy to save your new policy.

AWS CLI

Replace all user input with your own values.

Create a file called s3-policy.json with the following content.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetObject"
         ],
         "Resource":[
            "arn:aws:s3:::my-task-secrets-bucket/*"
         ],
         "Condition":{
            "ArnLike":{
            "aws:SourceArn":"arn:aws:ecs:region:123456789012:*"
            },
            "StringEquals":{
               "aws:SourceAccount":"123456789012"
            }
         }
      }
   ]
}

Use the following command to create the IAM policy using the JSON policy document file.
```
aws iam create-policy \
      --policy-name taskRolePolicy \
      --policy-document file://s3-policy.json
```

The following procedures describe how to create a task IAM role by attaching an IAM policy that you create.

AWS Management Console

To create the service role for Elastic Container Service (IAM console)

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane of the IAM console, choose Roles, and then choose Create role.
For Trusted entity type, choose AWS service.
For Service or use case, choose Elastic Container Service, and then choose the Elastic Container Service Task use case.
Choose Next.
For Add permissions, search for and choose the policy you created.
Choose Next.
For Role name, enter a name for your role. For this example, type AmazonECSTaskS3BucketRole to name the role.
Review the role, and then choose Create role.

AWS CLI

Replace all user input with your own values.

Create a file named ecs-tasks-trust-policy.json that contains the trust policy to use for the task IAM role. The file should contain the following. Replace the Region identifier and specify the AWS account number that you use when launching tasks.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Service":[
               "ecs-tasks.amazonaws.com"
            ]
         },
         "Action":"sts:AssumeRole",
         "Condition":{
            "ArnLike":{
            "aws:SourceArn":"arn:aws:ecs:us-west-2:111122223333:*"
            },
            "StringEquals":{
               "aws:SourceAccount":"111122223333"
            }
         }
      }
   ]
}

Create an IAM role named ecsTaskRole using the trust policy created in the previous step.


aws iam create-role \
      --role-name ecsTaskRole \
      --assume-role-policy-document file://ecs-tasks-trust-policy.json

Retrieve the ARN of the IAM policy you created using the following command. Replace taskRolePolicy with the name of the policy you created.
```
aws iam list-policies --scope Local --query 'Policies[?PolicyName==`taskRolePolicy`].Arn'
```
Attach the IAM policy you created to the ecsTaskRole role. Replace the policy-arn with the ARN of the policy that you created.
```
aws iam attach-role-policy \
      --role-name ecsTaskRole \
      --policy-arn arn:aws:iam:111122223333:aws:policy/taskRolePolicy
```

Permissions required for ECS Exec

The ECS Exec feature requires a task IAM role to grant containers the permissions needed for communication between the managed SSM agent (execute-command agent) and the SSM service. You should add the following permissions to a task IAM role and include the task IAM role in your task definition. For more information, see Adding and Removing IAM Policies in the IAM User Guide.

Use the following policy for your task IAM role to add the required SSM permissions.


{
   "Version": "2012-10-17",
   "Statement": [
       {
       "Effect": "Allow",
       "Action": [
            "ssmmessages:CreateControlChannel",
            "ssmmessages:CreateDataChannel",
            "ssmmessages:OpenControlChannel",
            "ssmmessages:OpenDataChannel"
       ],
      "Resource": "*"
      }
   ]
}

Amazon EC2 instances additional configuration

We recommend that you limit the permissions in your container instance role to the minimal list of permissions used in the AmazonEC2ContainerServiceforEC2Role managed IAM policy.

Your Amazon EC2 instances require at least version 1.11.0 of the container agent to use task role; however, we recommend using the latest container agent version. For information about checking your agent version and updating to the latest version, see Updating the Amazon ECS container agent. If you use an Amazon ECS-optimized AMI, your instance needs at least 1.11.0-1 of the ecs-init package. If your instances are using the latest Amazon ECS-optimized AMI, then they contain the required versions of the container agent and ecs-init. For more information, see Amazon ECS-optimized AMI.

If you are not using the Amazon ECS-optimized AMI for your container instances, add the --net=host option to your docker run command that starts the agent and the following agent configuration variables for your desired configuration (for more information, see Amazon ECS container agent configuration):

ECS_ENABLE_TASK_IAM_ROLE=true: Uses IAM roles for tasks for containers with the bridge and default network modes.
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true: Uses IAM roles for tasks for containers with the host network mode. This variable is only supported on agent versions 1.12.0 and later.

For an example run command, see Manually updating the Amazon ECS container agent (for non-Amazon ECS-Optimized AMIs). You will also need to set the following networking commands on your container instance so that the containers in your tasks can retrieve their AWS credentials:


sudo sysctl -w net.ipv4.conf.all.route_localnet=1
sudo iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679
sudo iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679

You must save these iptables rules on your container instance for them to survive a reboot. You can use the iptables-save and iptables-restore commands to save your iptables rules and restore them at boot. For more information, consult your specific operating system documentation.

To prevent containers run by tasks that use the awsvpc network mode from accessing the credential information supplied to the Amazon EC2 instance profile, while still allowing the permissions that are provided by the task role, set the ECS_AWSVPC_BLOCK_IMDS agent configuration variable to true in the agent configuration file and restart the agent. For more information, see Amazon ECS container agent configuration.

To prevent containers run by tasks that use the bridge network mode from accessing the credential information supplied to the Amazon EC2 instance profile, while still allowing the permissions that are provided by the task role, by running the following iptables command on your Amazon EC2 instances. This command doesn't affect containers in tasks that use the host or awsvpc network modes. For more information, see Network mode.

```
sudo yum install -y iptables-services; sudo iptables --insert DOCKER-USER 1 --in-interface docker+ --destination 169.254.169.254/32 --jump DROP
```
You must save this iptables rule on your Amazon EC2 instance for it to survive a reboot. When using the Amazon ECS-optimized AMI, you can use the following command. For other operating systems, consult the documentation for that operating system.
```
sudo iptables-save | sudo tee /etc/sysconfig/iptables && sudo systemctl enable --now iptables
```

External instance additional configuration

Your external instances require at least version 1.11.0 of the container agent to use task IAM roles; however, we recommend using the latest container agent version. For information about checking your agent version and updating to the latest version, see Updating the Amazon ECS container agent. If you are using an Amazon ECS-optimized AMI, your instance needs at least 1.11.0-1 of the ecs-init package. If your instances are using the latest Amazon ECS-optimized AMI, then they contain the required versions of the container agent and ecs-init. For more information, see Amazon ECS-optimized AMI.

ECS_ENABLE_TASK_IAM_ROLE=true: Uses IAM roles for tasks for containers with the bridge and default network modes.
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true: Uses IAM roles for tasks for containers with the host network mode. This variable is only supported on agent versions 1.12.0 and later.


sudo sysctl -w net.ipv4.conf.all.route_localnet=1
sudo iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679
sudo iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Task execution IAM role

Configuration for the task role on EC2 Windows