An Amazon ECS task definition can reference both a task role and a task execution role. What is each one for, who uses it, and how do the symptoms differ when one of them is missing a permission?

## Two roles because there are two actors A container running on ECS involves two parties that call AWS. Before your process exists, something must fetch the image, wire up logging, and resolve secrets into the container's environment. After it starts, your code calls AWS services. AWS refuses to blur those: the first actor is the ECS/Fargate infrastructure and uses the **task execution role**; the second is your application and uses the **task role**. Both are ordinary IAM roles whose trust policy allows `ecs-tasks.amazonaws.com` to assume them; only their consumers and their timing differ. ## The task execution role Set as `executionRoleArn` in the task definition, this role is used by the agent/infrastructure at task-launch time for: - **Pulling the image** from Amazon ECR — `ecr:GetAuthorizationToken`, `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`. Public images from other registries need no permission here. - **Log delivery** for the `awslogs` driver — `logs:CreateLogStream` and `logs:PutLogEvents` (plus `logs:CreateLogGroup` if you let ECS create the group). - **Secret injection.** If the container definition has a `secrets` block pointing at Secrets Manager ARNs or SSM parameters, the *execution* role — not the task role — must be allowed `secretsmanager:GetSecretValue` or `ssm:GetParameters`, and `kms:Decrypt` on the key if the secret is encrypted with a customer managed key. This is the single most common ECS IAM mistake: the permission is added to the task role, where it does nothing. The managed policy `AmazonECSTaskExecutionRolePolicy` covers the ECR and CloudWatch Logs basics; secret access is yours to add. ## The task role Set as `taskRoleArn`, this is the workload's identity. ECS injects an environment variable into every container in the task pointing at a credentials path on the local agent endpoint; the AWS SDKs know to call it as part of their default credential lookup and receive temporary STS credentials scoped to that role, refreshed automatically. Your code configures nothing. ```json { "family": "orders", "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole", "taskRoleArn": "arn:aws:iam::111122223333:role/orders-task", "containerDefinitions": [{ "name": "api", "image": "111122223333.dkr.ecr.eu-west-1.amazonaws.com/orders:1.4.2", "secrets": [{ "name": "DB_PASSWORD", "valueFrom": "arn:aws:secretsmanager:eu-west-1:111122223333:secret:orders/db-AbCdEf" }] }] } ``` The task role is per task definition, so it is the natural least-privilege boundary: the orders service gets its own role with its own bucket and table, and a compromise there does not reach the payments service's data. Sharing one fat role across every task in a cluster throws that away. ## Reading the failure The two roles fail at different moments, which makes diagnosis fast: - Task stops before RUNNING with `CannotPullContainerError`, or with a message about the log configuration, or `ResourceInitializationError` mentioning a secret → **execution role** (or, on a private subnet, no route to ECR/Secrets Manager, which needs a NAT path or interface endpoints). - Task is healthy, your logs show `AccessDenied` calling S3/DynamoDB/SQS → **task role**. Confirm with `aws sts get-caller-identity` from inside the container (`ecs execute-command`) — it should print the task role's assumed-role ARN. ## The EC2 launch-type trap On the Fargate launch type a task is isolated and only ever sees its task role. On the EC2 launch type the container shares a host that has its own instance profile, and unless the agent is configured to block it, a container in bridge mode can reach the instance metadata endpoint and pick up the *instance* role. That means a task might quietly work while its task role grants nothing — and it means the node role's permissions become every container's permissions. Keep the instance profile minimal (what the ECS agent itself needs) and block container access to the metadata endpoint; the credential shadowing is otherwise invisible until an audit. ## Rule of thumb If a permission is needed to *start* the container, it belongs on the execution role. If it is needed by code *inside* the container, it belongs on the task role. Every task definition should name both, and neither should be shared more widely than the workload it serves.