# ECS task role vs task execution role

IAM policy examples · Updated 17 November 2026

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

## 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](https://cloudconsole.dev/errors/ecs-cannotpullcontainererror), [ResourceInitializationError](https://cloudconsole.dev/errors/ecs-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.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](https://cloudconsole.dev/how-to/ecs-exec-into-container).
- **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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Amazon ECS task execution IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html)
- [Amazon ECS task IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)

## Related

- [CannotPullContainerError: pull image manifest has been retried](https://cloudconsole.dev/errors/ecs-cannotpullcontainererror)
- [ResourceInitializationError: unable to pull secrets or registry auth](https://cloudconsole.dev/errors/ecs-resourceinitializationerror)
- [IAM policy: push and pull one ECR repository](https://cloudconsole.dev/iam/ecr-push-pull)
- [IAM policy: read one secret from Secrets Manager](https://cloudconsole.dev/iam/secrets-manager-read-one-secret)
- [iam:PassRole: policy example and why it matters](https://cloudconsole.dev/iam/iam-passrole)
- [How to exec into an ECS container](https://cloudconsole.dev/how-to/ecs-exec-into-container)

---

Source: https://cloudconsole.dev/iam/ecs-task-role-vs-execution-role

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
