Checking for the task execution (ecsTaskExecutionRole) role in the IAM console Creating the task execution (ecsTaskExecutionRole) role Required IAM permissions for private registry authentication Required IAM permissions for Amazon ECS secrets Optional IAM permissions for Fargate tasks pulling Amazon ECR images over interface endpoints

Amazon ECS task execution IAM role

The task execution role grants the Amazon ECS container and Fargate agents permission to make AWS API calls on your behalf. The task execution IAM role is required depending on the requirements of your task. You can have multiple task execution roles for different purposes and services associated with your account.

The following are common use cases for a task execution IAM role:

Your task is hosted on AWS Fargate or on an external instance and...
- is pulling a container image from an Amazon ECR private repository.
- sends container logs to CloudWatch Logs using the awslogs log driver. For more information, see Using the awslogs log driver.
Your tasks are hosted on either AWS Fargate or Amazon EC2 instances and...
- is using private registry authentication. For more information, see Required IAM permissions for private registry authentication.
- the task definition is referencing sensitive data using Secrets Manager secrets or AWS Systems Manager Parameter Store parameters. For more information, see Required IAM permissions for Amazon ECS secrets.

Note

The task execution role is supported by Amazon ECS container agent version 1.16.0 and later.

Amazon ECS provides the managed policy named AmazonECSTaskExecutionRolePolicy which contains the permissions the common use cases described above require. It might be necessary to add inline policies to your task execution role for special use cases which are outlined below.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

An Amazon ECS task execution role can be created for you in the Amazon ECS console; however, you should manually attach the managed IAM policy for tasks to allow Amazon ECS to add permissions for future features and enhancements as they are introduced. You can use the following procedure to check and see if your account already has the Amazon ECS task execution role and to attach the managed IAM policy if needed.

Checking for the task execution (`ecsTaskExecutionRole`) role in the IAM console

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles.
In the search box, enter ecsTaskExecutionRole. If the role does exist, choose the role to view the attached policies.
On the Permissions tab, verify that the AmazonECSTaskExecutionRolePolicy is attached to the role.
1. Choose Add Permissions, Attach policies.
2. To narrow the available policies to attach, for Filter, enter AmazonECSTaskExecutionRolePolicy.
3. Check the box to the left of the AmazonECSTaskExecutionRolePolicy policy, and then choose Attach policy.
Choose Trust relationships.
Verify that the trust relationship contains the following policy. If the trust relationship matches the policy below, choose Cancel. If the trust relationship does not match, choose Edit trust policy, copy the policy into the Policy Document window and choose Update policy.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

Creating the task execution (`ecsTaskExecutionRole`) role

If your account does not already have a task execution role, use the following steps to create the role.

To create a task execution IAM role (AWS Management Console)

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles, Create role.
In the Trusted entity type section, choose AWS service, Elastic Container Service.
For Use case, choose Elastic Container Service Task, and then choose Next.
In the Attach permissions policy section, do the following:
1. Search for AmazonECSTaskExecutionRolePolicy, then select the policy.
2. Under Set permissions boundary - optional, choose Create role without a permissions boundary.
3. Choose Next.
Under Role details, do the following:
1. For Role name, type ecsTaskExecutionRole.
2. For Add tags (optional), specify any custom tags to associate with the policy .
Choose Create role.

To create a task execution IAM role (AWS CLI)

Create a file named ecs-tasks-trust-policy.json that contains the trust policy to use for the IAM role. The file should contain the following:


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

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


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

Attach the AWS managed AmazonECSTaskExecutionRolePolicy policy to the ecsTaskExecutionRole role. This policy provides


aws iam attach-role-policy \
      --role-name ecsTaskExecutionRole \
      --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

Required IAM permissions for private registry authentication

The Amazon ECS task execution role is required to use the private registry authentication feature. This allows the container agent to pull the container image. For more information, see Private registry authentication for tasks.

To provide access to the secrets that you create, manually add the following permissions as an inline policy to the task execution role. For more information, see Adding and Removing IAM Policies.

secretsmanager:GetSecretValue
kms:Decrypt—Required only if your key uses a custom KMS key and not the default key. The ARN for your custom key should be added as a resource.

An example policy adding the permissions is shown below.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "ssm:GetParameters",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<region>:<aws_account_id>:secret:secret_name",
        "arn:aws:kms:<region>:<aws_account_id>:key/key_id"     
      ]
    }
  ]
}

Required IAM permissions for Amazon ECS secrets

To use the Amazon ECS secrets feature, you must have the Amazon ECS task execution role and reference it in your task definition. This allows the container agent to pull the necessary AWS Systems Manager or Secrets Manager resources. For more information, see Passing sensitive data to a container.

To provide access to the AWS Systems Manager Parameter Store parameters that you create, manually add the following permissions as an inline policy to the task execution role. For more information, see Adding and Removing IAM Policies.

ssm:GetParameters—Required if you are referencing a Systems Manager Parameter Store parameter in a task definition.
secretsmanager:GetSecretValue—Required if you are referencing a Secrets Manager secret either directly or if your Systems Manager Parameter Store parameter is referencing a Secrets Manager secret in a task definition.
kms:Decrypt—Required only if your secret uses a custom KMS key and not the default key. The ARN for your custom key should be added as a resource.

The following example policy adds the required permissions:


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "kms:Decrypt"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<region>:<aws_account_id>:secret:<secret_name>",
        "arn:aws:kms:<region>:<aws_account_id>:key/<key_id>"
      ]
    }
  ]
}

Optional IAM permissions for Fargate tasks pulling Amazon ECR images over interface endpoints

When launching tasks that use the Fargate launch type that pull images from Amazon ECR when Amazon ECR is configured to use an interface VPC endpoint, you can restrict the tasks access to a specific VPC or VPC endpoint. Do this by creating a task execution role for the tasks to use that use IAM condition keys.

Use the following IAM global condition keys to restrict access to a specific VPC or VPC endpoint. For more information, see AWS Global Condition Context Keys.

aws:SourceVpc—Restricts access to a specific VPC.
aws:SourceVpce—Restricts access to a specific VPC endpoint.

The following task execution role policy provides an example for adding condition keys:

Important

The ecr:GetAuthorizationToken API action cannot have the aws:sourceVpc or aws:sourceVpce condition keys applied to it because the GetAuthorizationToken API call goes through the elastic network interface owned by AWS Fargate rather than the elastic network interface of the task.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:sourceVpce": "vpce-xxxxxx",
                    "aws:sourceVpc": "vpc-xxxxx"
                }
            }
        }
    ]
}

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

Using service-linked roles

Task IAM role