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.

This 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.

This 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.

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

There you can see that the task role contains a trust relationship with the "ecs-tasks.amazonaws.com" service.

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.

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.

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.