Bayplan

Free tool

ECS IAM policy generator

Pick what your tasks use and get least-privilege IAM policies for the task execution role, the task role and your container instances, as JSON or Terraform.

Your setup

Add your application's own permissions, for S3 or DynamoDB for example, to this role yourself.

Task execution role

ecsTaskExecutionRole

  • Without your 12-digit account ID, the resources use * for the account.
  • No repositories named, so the role can pull from every repository.
  • No log groups named, so the role can write to every log group.

Permissions policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetEcrToken",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PullImages",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:*:*:repository/*"
    },
    {
      "Sid": "WriteLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:*"
    }
  ]
}

Trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Task role

ecsTaskRole

  • Add your account ID to limit the trust policy to your own ECS tasks.

No permissions selected. The role still needs its trust policy so tasks can assume it.

Trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Everything runs in your browser; nothing you enter is sent anywhere. Your choices are kept in the page's URL, so you can bookmark or share them. Check the policies before you use them in production.

Questions

What is the difference between the ECS task role and the task execution role?

The task execution role is used by ECS itself to start your task: it pulls the image, writes container logs and reads the secrets referenced in the task definition. The task role is used by your application inside the container, for example to read from S3 or to accept ECS Exec sessions. A task can have both, and they should not share permissions.

What permissions does the ECS task execution role need?

To pull from a private ECR repository: ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer and ecr:BatchGetImage. To write logs with the awslogs driver: logs:CreateLogStream and logs:PutLogEvents. For secrets in the task definition: secretsmanager:GetSecretValue or ssm:GetParameters, plus kms:Decrypt for a customer-managed KMS key. The AWS managed policy AmazonECSTaskExecutionRolePolicy grants the ECR and log actions for every resource; this generator scopes them to yours.

Which permissions does ECS Exec need?

The task role needs ssmmessages:CreateControlChannel, ssmmessages:CreateDataChannel, ssmmessages:OpenControlChannel and ssmmessages:OpenDataChannel. The person connecting needs ecs:ExecuteCommand on the cluster and task. The service also has to have ECS Exec turned on, and the task needs a network route to the SSM endpoint.

Why does my task fail with CannotPullContainerError or ResourceInitializationError?

Often because the task execution role is missing. Or it lacks the ECR actions on the repository, or secretsmanager:GetSecretValue, ssm:GetParameters or kms:Decrypt on a secret the task definition references. The same errors also appear when the task has no network route to ECR, Secrets Manager or Parameter Store, so check the subnet's NAT gateway or VPC endpoints too.

Does the ECS task role need a confused deputy condition?

AWS recommends it. With aws:SourceAccount and aws:SourceArn in the trust policy, only ECS tasks in your account can assume the role. Enter your account ID and the generator adds both conditions to the task role.

What does the container instance role need for ECS on EC2?

The AWS managed policy AmazonEC2ContainerServiceforEC2Role, which lets the ECS agent register the instance, pull images and write logs, attached to a role that EC2 can assume and to an instance profile. Add AmazonSSMManagedInstanceCore if you want to reach the instances with Session Manager instead of SSH.

Setting up ECS Exec? Read how to open a shell in an ECS container. Planning a new stack? Try the ECS cost calculator.