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.
Note
These permissions are made available to the agent running on your instance by Amazon ECS periodically sending it the role's temporary credentials, but they aren't directly accessible by the containers in the task. For the IAM permissions that your application code inside the container needs to run, see Amazon ECS task IAM role.
The following are common use cases for a task execution IAM role:
-
Your task is hosted on AWS Fargate, Amazon ECS Managed Instances, or an external instance and:
-
pulls a container image from an Amazon ECR private repository.
-
pulls 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
awslogslog driver. For more information, see Send Amazon ECS logs to CloudWatch.
-
-
Your tasks are hosted on either AWS Fargate or Amazon EC2 instances and:
-
uses private registry authentication. For more information, see Private registry authentication permissions.
-
uses Runtime Monitoring.
-
the task definition references sensitive data using Secrets Manager secrets or AWS Systems Manager Parameter Store parameters. For more information, see Secrets Manager or Systems Manager permissions.
-
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 previously described require. For more
information, see AmazonECSTaskExecutionRolePolicy in the AWS Managed
Policy Reference Guide. It might be necessary to add inline policies to your
task execution role for special use cases
The Amazon ECS console creates a task execution role. You can 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.
If you pull images as an authenticated user, you're less likely to be
impacted by the changes that occurred to Docker Hub
usage and limits
By using Amazon ECR and Amazon ECR Public, you can avoid the limits imposed by Docker. If you pull images from Amazon ECR, this also helps shorten network pull times and reduces data transfer changes when traffic leaves your VPC.
When you use Fargate, you must authenticate to a private image registry
using repositoryCredentials. It's not possible to set the Amazon ECS
container agent environment variables ECS_ENGINE_AUTH_TYPE or
ECS_ENGINE_AUTH_DATA or modify the ecs.config file
for tasks hosted on Fargate. For more information, see Private registry authentication for tasks.
Creating the task execution role
If your account doesn't already have a task execution role, use the following steps to create the role.