CloudConsole

ECS task role vs task execution role

Updated 17 November 2026 · How we write and check guides

Short answer

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.

Policy diagram: 4 statement(s); first Allow ecr:GetAuthorizationToken on * (all resources)
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

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 roleTask role
Used byThe ECS agent / Fargate, before and around your containerYour application code, through the SDK
Typical permissionsECR pull, CloudWatch Logs, secrets in the task definitionS3, DynamoDB, SQS, whatever the app calls
Task definition fieldexecutionRoleArntaskRoleArn
Missing it causesCannotPullContainerError, ResourceInitializationErrorAccessDenied 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.json

Check 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 text

A 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:OpenControlChannel and ssmmessages:OpenDataChannel. See ECS Exec.
  • Secrets encrypted with a customer managed KMS key: the execution role also needs kms:Decrypt on that key.
  • Pulling from Docker Hub with credentials stored in Secrets Manager uses the same secretsmanager:GetSecretValue permission 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.

When this happens away from your desk

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

Sources