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. For the IAM permissions that your application needs to run, see Task IAM role.
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.
-
is pulling a container image from an Amazon ECR private repository in a different account from the account that runs the task.
-
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.
-
is using Runtime Monitoring.
-
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 IAM console
search to search for ecsTaskExecutionRole
and see if your account already has
the task execution role. For more information, see IAM console search in the
IAM user guide.
Creating the task execution (ecsTaskExecutionRole
)
role
If your account doesn't already have a task execution role, use the following steps to create the role.
Required IAM permissions for private registry authentication
The Amazon ECS task execution role is required to use this feature. This allows the container agent to pull the container image.
To provide access to the secrets that you create, 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 Amazon Resource Name (ARN) for your custom key must be added as a resource.
The following is an example inline policy that adds the permissions.
{ "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 Passing sensitive data to a container.
Using Secrets Manager
To provide access to the Secrets Manager secrets that you create, manually add the following permission to the task execution role. For information about how to manage permissions, see Adding and Removing IAM identity permissions in the IAM User Guide.
-
secretsmanager:GetSecretValue
– Required if you are referencing a Secrets Manager secret. Adds the permission to retrieve the secret from Secrets Manager.
The following example policy adds the required permissions.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:
region
:aws_account_id
:secret:secret_name
" ] } ] }
Using Systems Manager
Important
For tasks that use the EC2 launch type, you must use
the ECS agent configuration variable
ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true
to
use this feature. You can add it to the
./etc/ecs/ecs.config
file during container instance
creation or you can add it to an existing instance and then restart
the ECS agent. For more information, see Amazon ECS container agent configuration.
To provide access to the Systems Manager Parameter Store parameters that you create, manually add the following permissions as a policy to the task execution role. For information about how to manage permissions, see Adding and Removing IAM identity permissions in the IAM User Guide.
-
ssm:GetParameters
— Required if you are referencing a Systems Manager Parameter Store parameter in a task definition. Adds the permission to retrieve Systems Manager parameters. -
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. Adds the permission to retrieve the secret from Secrets Manager. -
kms:Decrypt
— Required only if your secret uses a customer managed key and not the default key. The ARN for your custom key should be added as a resource. Adds the permission to decrypt the customer managed key .
The following example 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
" ] } ] }
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
" } } } ] }