Creating an IAM role and policy for your tasks IAM permissions required for ECS Exec Specifying an IAM role for your tasks

Task IAM 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. For the IAM permissions that Amazon ECS needs to pull container images and run the task, see Amazon ECS task execution IAM role.

If your containerized applications need to call AWS APIs, they must sign their AWS API requests with AWS credentials, and a task IAM role provides a strategy for managing credentials for your applications to use, similar to the way that an Amazon EC2 instance profile provides credentials to Amazon EC2 instances. Instead of creating and distributing your AWS credentials to the containers or using the Amazon EC2 instance’s role, you can associate an IAM role with an Amazon ECS task definition or RunTask API operation. Your containers can then use the AWS SDK or AWS CLI to make API requests to authorized AWS services.

The following explain the benefits of using IAM roles with your tasks.

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.
Auditability: 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.

You can specify a task IAM role in your task definitions, or you can use a taskRoleArn override when running a task manually with the RunTask API operation. The Amazon ECS agent receives a payload message for starting the task with additional fields that contain the role credentials. The Amazon ECS agent sets a unique task credential ID as an identification token and updates its internal credential cache so that the identification token for the task points to the role credentials that are received in the payload. The Amazon ECS agent populates the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable in the Env object (available with the docker inspect container_id command) for all containers that belong to this task with the following relative URI: /credential_provider_version/credentials?id=task_credential_id.

From inside the container, you can query the credential endpoint with the following command:


curl 169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

Output:


{
    "AccessKeyId": "ACCESS_KEY_ID",
    "Expiration": "EXPIRATION_DATE",
    "RoleArn": "TASK_ROLE_ARN",
    "SecretAccessKey": "SECRET_ACCESS_KEY",
    "Token": "SECURITY_TOKEN_STRING"
}

Creating an IAM role and policy for your tasks

When creating an IAM policy for your tasks to use, the policy should include the permissions that you would like 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 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. It is recommended that you use the aws:SourceAccount or aws:SourceArn condition keys to scope the permissions further to prevent the confused deputy security issue. These condition keys can be specified in the trust relationship or in the IAM policy associated with the role. 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 is an example trust policy. You should 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 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.

To create an IAM policy for your tasks (AWS Management Console)

In this example, we create a policy to allow read-only access to an Amazon S3 bucket. You could store database credentials or other secrets in this bucket, and the containers in your task can read the credentials from the bucket and load them into your application.

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies and then choose Create Policy.
Follow the steps under one of the following tabs, which shows you how to use the visual or JSON editors.

Using the visual editor

For Service, choose S3.
For Actions, expand the Read option and select GetObject.
For Resources, select Add ARN and enter the full Amazon Resource Name (ARN) of your Amazon S3 bucket.
(Optional) For Request conditions, select Add condition. This is recommended to prevent the confused deputy security issue. 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.
1. For Condition key, select either aws:SourceAccount or aws:SourceArn. For more information about these global condition keys, see AWS global condition context keys in the IAM User Guide.
2. For Operator, select StringEquals if you specified the aws:SourceAccount condition key or ArnLike if you specified the aws:SourceArn condition key.
3. For Value, specify your AWS account ID if you specified the aws:SourceAccount condition key or the Amazon Resource Name (ARN) of your Amazon ECS task if you specified the aws:SourceArn condition key. You may use wildcards, for example aws:ecs:*:accountId:* which will work for all tasks in your account.
4. Choose Add to save the condition key. Repeat these steps for each condition key you want to add to the policy.
Choose Next: Tags and add any resource tags to the policy to help you organize them and then choose Next: Review.
On the Review policy page, for Name type your own unique name, such as AmazonECSTaskS3BucketPolicy. You may specify an optional description for the policy as well.
When the policy is complete, choose Create policy to finish.

Using the JSON editor

In the policy document field, paste the policy to apply to your tasks. The example below allows permission to the my-task-secrets-bucket Amazon S3 bucket. It includes a condition statement, which you can use to specify either a specific task using its Amazon Resource Name (ARN) or a specific account ID. This provides a way to further scope the permission for additional security. This is recommended to prevent the confused deputy security issue. 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 is an example permissions policy. You can modify the policy to suit your specific needs. You should replace the Region identifier and specify the AWS account number that you use when launching tasks.
```
{
   "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:111122223333:*"
            },
            "StringEquals":{
               "aws:SourceAccount":"111122223333"
            }
         }
      }
   ]
}
```
Choose Next: Tags and add any resource tags to the policy to help you organize them and then choose Next: Review.
On the Review policy page, for Name type your own unique name, such as AmazonECSTaskS3BucketPolicy. You may specify an optional description for the policy as well.
When the policy is complete, choose Create policy to finish.

To create an IAM role for your tasks (AWS Management Console)

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles, Create role.
For Select trusted entity section, choose AWS service.
For Use case, using the drop down menu, select Elastic Container Service and then the Elastic Container Service Task use case and then choose Next.
For Add permissions, search for and select the policy to use for your tasks (in this example AmazonECSTaskS3BucketPolicy, and then choose Next.
On Step 3: Name, review, and create, do the following:
1. For Role name, enter a name for your role. For this example, type AmazonECSTaskS3BucketRole to name the role.
2. (Optional) For Description. specify a description for this IAM role.
3. Review the trusted entity and permissions policy for the role.
4. For Add tags (Optional), enter any metadata tags you want to associate with the IAM role, and then choose Create role.

IAM 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.

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": "*"
      }
   ]
}

Specifying an IAM role for your tasks

After you have created a role and attached a policy to that role, you can run tasks that assume the role. You have several options to do this:

Specify an IAM role for your tasks in the task definition. You can create a new task definition or a new revision of an existing task definition and specify the role you created previously. If you use the console to create your task definition, choose your IAM role in the Task Role field. If you use the AWS CLI or SDKs, specify the Amazon Resource Name (ARN) of your task role using the taskRoleArn parameter. For more information, see Creating a task definition using the console.

Note
This option is required if you want to use IAM task roles in an Amazon ECS service.
Specify an IAM task role override when running a task. You can specify an IAM task role override when running a task. If you use the classic console to run your task, choose Advanced Options and then choose your IAM role in the Task Role field. If you use the AWS CLI or SDKs, specify your task role ARN using the taskRoleArn parameter in the overrides JSON object. For more information, see Run a standalone task in the classic Amazon ECS console.

Note

In addition to the standard Amazon ECS permissions required to run tasks and services, users also require iam:PassRole permissions to use IAM roles for tasks.

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

ECS Anywhere IAM role