ECS task role vs task execution role
The task execution role is used by ECS itself to start the task: pull the image from ECR, write container logs and fetch secrets referenced in the task definition. The task role is what your application code runs as when it calls AWS. Both trust ecs-tasks.amazonaws.com; giving app permissions to the execution role does nothing for your code.
Execution role policy
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EcrAuth",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
},
{
"Sid": "PullImage",
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage"
],
"Resource": "arn:aws:ecr:eu-west-2:123456789012:repository/orders-api"
},
{
"Sid": "ContainerLogs",
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:eu-west-2:123456789012:log-group:/ecs/orders-api:*"
},
{
"Sid": "InjectSecrets",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"ssm:GetParameters"
],
"Resource": [
"arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/orders-db-??????",
"arn:aws:ssm:eu-west-2:123456789012:parameter/orders-api/*"
]
}
]
}This is the scoped equivalent of the managed AmazonECSTaskExecutionRolePolicy (which covers ECR and logs on every resource) plus secrets for this one service.
Which role does what
| Task execution role | Task role | |
|---|---|---|
| Used by | The ECS agent / Fargate, before and around your container | Your application code, through the SDK |
| Typical permissions | ECR pull, CloudWatch Logs, secrets in the task definition | S3, DynamoDB, SQS, whatever the app calls |
| Task definition field | executionRoleArn | taskRoleArn |
| Missing it causes | CannotPullContainerError, ResourceInitializationError | AccessDenied in your application logs |
Trust policy for both roles
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ecs-tasks.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:ecs:eu-west-2:123456789012:*"
}
}
}
]
}The conditions protect against the confused-deputy problem: only ECS acting for tasks in your own account can assume the role.
aws iam create-role --role-name orders-api-task-execution \
--assume-role-policy-document file://ecs-trust.json
aws iam put-role-policy --role-name orders-api-task-execution \
--policy-name pull-logs-secrets --policy-document file://execution.jsonCheck which role a task used
aws ecs describe-task-definition --task-definition orders-api \
--query 'taskDefinition.{exec:executionRoleArn,task:taskRoleArn}'
aws ecs describe-tasks --cluster prod --tasks 0123456789abcdef0123456789abcdef \
--query 'tasks[0].[lastStatus,stoppedReason]' --output textA stopped reason mentioning ECR, logs or secrets points at the execution role; an AccessDenied in your own application logs points at the task role.
Both roles can be shared by several task definitions, but giving each service its own task role keeps one compromised container from reaching another service's data.
Task role extras and mistakes
- ECS Exec needs the task role to allow
ssmmessages:CreateControlChannel,ssmmessages:CreateDataChannel,ssmmessages:OpenControlChannelandssmmessages:OpenDataChannel. See ECS Exec. - Secrets encrypted with a customer managed KMS key: the execution role also needs
kms:Decrypton that key. - Pulling from Docker Hub with credentials stored in Secrets Manager uses the same
secretsmanager:GetSecretValuepermission on the execution role. - Putting app permissions on the execution role, or the reverse, is the most common mistake. The SDK inside the container only ever sees the task role's credentials.
- No task role at all: on EC2 launch type, the SDK may silently fall back to the instance's role, which usually has different and broader permissions. Always set
taskRoleArn.
Questions
Do I need both an ECS task role and an execution role?
You need the execution role whenever ECS pulls from private ECR, sends logs with awslogs or injects secrets. You need a task role whenever your code calls AWS. Most services use both.
What is the trust policy for an ECS task execution role?
Allow the service principal ecs-tasks.amazonaws.com to call sts:AssumeRole, ideally with aws:SourceAccount and aws:SourceArn conditions as above.
A service stuck at zero running tasks often comes down to the execution role. The stopped task's reason, readable from a phone, names the failing step: image pull, logs or secrets.
About the app → · Download on the App Store