All posts

ECS task role vs task execution role: which one does what

The difference between the AWS ECS task role and task execution role, the errors you get when you mix them up and a minimal policy for each.

Every ECS task definition has two IAM role fields that look almost the same: taskRoleArn and executionRoleArn. Mixing them up is one of the most common reasons a task fails to start, or starts and then can’t reach S3.

The short version

  • The task execution role is used by ECS itself to start your task: pull the image, send logs and fetch secrets.
  • The task role is used by your application for its own AWS calls: reading from S3, writing to DynamoDB, publishing to SQS.

Both must trust the ecs-tasks.amazonaws.com service principal. The free ECS IAM policy generator writes both, scoped to your repositories, log groups and secrets.

The task execution role

ECS (on Fargate) or the ECS agent (on EC2) assumes this role before your code runs. It needs permissions for:

  • pulling images from private ECR repositories,
  • writing to CloudWatch Logs with the awslogs log driver,
  • reading values referenced in the task definition’s secrets from Secrets Manager or Parameter Store, plus kms:Decrypt if they use a customer-managed key.

AWS provides the managed policy AmazonECSTaskExecutionRolePolicy, which covers ECR and CloudWatch Logs. Add secrets access separately, scoped to the specific secrets:

{
  "Effect": "Allow",
  "Action": ["secretsmanager:GetSecretValue"],
  "Resource": "arn:aws:secretsmanager:eu-central-1:123456789012:secret:prod/api/*"
}

Your application never sees these credentials.

The task role

The task role’s credentials are made available inside the container through the container credentials endpoint. ECS sets AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, and every AWS SDK picks it up automatically, so your code doesn’t need access keys.

Give it exactly what the application calls:

{
  "Effect": "Allow",
  "Action": ["s3:GetObject", "s3:PutObject"],
  "Resource": "arn:aws:s3:::acme-uploads/*"
}

A task role is optional. A task that makes no AWS calls doesn’t need one. ECS Exec is the exception: its SSM permissions go on the task role, because the agent runs inside your task.

The trust policy

Both roles use the same trust policy. Adding conditions on the source account and ARN protects against the confused-deputy problem:

{
  "Effect": "Allow",
  "Principal": { "Service": "ecs-tasks.amazonaws.com" },
  "Action": "sts:AssumeRole",
  "Condition": {
    "StringEquals": { "aws:SourceAccount": "123456789012" },
    "ArnLike": { "aws:SourceArn": "arn:aws:ecs:eu-central-1:123456789012:*" }
  }
}

Errors and which role to fix

SymptomRole to fix
CannotPullContainerError with access denied from ECRExecution role
ResourceInitializationError: unable to pull secrets or registry authExecution role (or no network route to ECR or Secrets Manager)
Task stops right away, nothing in CloudWatch LogsExecution role is missing logs:CreateLogStream or logs:PutLogEvents
The app logs AccessDenied ... assumed-role/<name>/...Task role (the role name in the message tells you which one)
The app uses the EC2 instance’s role insteadNo task role set, so on EC2 the SDK falls back to the instance profile

The last one is subtle. On the EC2 launch type, a task without a task role can fall back to the instance’s credentials, which usually have far more permissions than any one task should. Set a task role on every task that calls AWS, and consider blocking access to the instance metadata endpoint from tasks.

Good habits

  • One task role per service. Shared roles grow until every service can do everything.
  • One execution role per environment or team is usually fine, since it only covers starting tasks.
  • Scope secrets access to path prefixes rather than *.
  • Check with IAM Access Analyzer which permissions a task role actually uses, and remove the rest.

If you remember one thing: the execution role gets the task running, and the task role is what the running code uses.