Task role vs task execution role in Amazon ECS


When you’re using CloudFormation, Terraform, or AWS CDK to deploy Amazon ECS containers with ECS Fargate or EC2.

You might notice that the ECS tasks contain two types of roles, one found in the task definition called the execution role, and the task role can be found in the ECS task that controls the running containers.

In short, ECS task roles allow the containers in your task to assume an IAM role to call AWS APIs without having to use AWS Credentials inside the containers. That means the application inside the container can access other AWS services like sending a notification to Amazon SNS or accessing an S3 bucket.

ECS task execution roles grant the ECS agents permission to make AWS API calls who are responsible for managing the tasks in the cluster. That means the task is able to send container logs to CloudWatch or pull a container image from Amazon ECR.

In this blog post, we’ll dive deeper to find out what the differences are between the ECS task role and the ECS task execution role in Amazon ECS.

What is an Amazon ECS task role?

The ECS task role is essential when the application in your ECS container running on Fargate or EC2 needs to access other AWS Services like an S3 bucket.

When you visit the Amazon ECS service in the AWS Console and pick a task, you should see the task role.

Amazon ECS task overview with task role highlighted

If you click on the task role it will show you the details in the IAM Management console.

Amazon ECS task role trusted entities in IAM Management console

There you can see that the task role contains a trust relationship with the "ecs-tasks.amazonaws.com" service. This that it allows the containers to assume the role which can then be used to access other AWS Services.

On the permissions tab, you see which permissions policies are attached. These are regularly managed or inline policies. In the example below we’ve given the task role access to the S3 Service.

Amazon ECS task role permissions in IAM Management console

What is an Amazon ECS task execution role?

The ECS task execution role grants the Amazon ECS container and Fargate agents permission to make AWS API calls on your behalf. The ECS agent is responsible for managing the tasks in your ECS cluster and manages all the overhead.

The execution role can be found in the task definition of your ECS task.

Amazon ECS task definition overview with task execution role highlighted

To cover to most common use cases, like pulling container images from Amazon ECR and sending container logs to CloudWatch logs you need the following permissions.

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

Conclusion

In this article, you’ve learned the difference between an Amazon ECS task role and a task execution role.

You need both roles in order to start up containers in your ECS tasks by getting permission to pull the Amazon ECR container image and getting the ability to access other AWS services from within the container.


Danny Steenman

Is a Principal Cloud Consultant with a background in DevOps Engineering and thorough hands-on experience in architecting and building highly scalable distributed systems on AWS Cloud using Infrastructure as Code.

A prominent leader who is passionate about sharing AWS technical expertise by writing technical articles.