Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

Amazon ECS Task Execution IAM Role

The Amazon ECS container agent makes calls to the Amazon ECS API on your behalf, so it requires an IAM policy and role for the service to know that the agent belongs to you. The following are the use cases for when the task execution IAM role is needed:

Note

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

The AmazonECSTaskExecutionRolePolicy policy is shown below.

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

The Amazon ECS task execution role is automatically created for you in the Amazon ECS console first-run experience; 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.

To check for the ecsTaskExecutionRole in the IAM console

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles.

  3. Search the list of roles for ecsTaskExecutionRole. If the role does not exist, use the procedure below to create the role. If the role does exist, select the role to view the attached policies.

  4. Choose Permissions. Ensure that the AmazonECSTaskExecutionRolePolicy managed policy is attached to the role. If the policy is attached, your Amazon ECS task execution role is properly configured. If not, follow the substeps below to attach the policy.

    1. Choose Attach policy.

    2. To narrow the available policies to attach, for Filter, type AmazonECSTaskExecutionRolePolicy.

    3. Check the box to the left of the AmazonECSTaskExecutionRolePolicy policy and choose Attach policy.

  5. Choose Trust relationships, Edit trust relationship.

  6. 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, copy the policy into the Policy Document window and choose Update Trust Policy.

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

To create the ecsTaskExecutionRole IAM role

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, Create role.

  3. In the Select type of trusted entity section, choose Elastic Container Service.

  4. For Select your use case, choose Elastic Container Service Task, then choose Next: Permissions.

  5. In the Attach permissions policy section, search for AmazonECSTaskExecutionRolePolicy, select the policy, and then choose Next: Review.

  6. For Role Name, type ecsTaskExecutionRole and choose Create role.

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 inline policy adding the permissions is shown below.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt", "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 Specifying Sensitive Data.

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 inline policy adds the required permissions:

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