Infra roles

These roles are shared by the EC2 and Fargate paths. Confirm $NAME is set from Prerequisites. The EC2 instance role is created later under EC2 capacity.

Two roles, two different trust principals — the thing to get right is which AWS service is allowed to assume each.

ecs-gw-lab-gateway-infra

Trusted by

ecs.amazonaws.com

Policy

AmazonECSInfrastructureRoleForGatewayHostSharedALB

Lets ECS

Create the ALB, security groups, and ACM certificates for the gateway

ecs-gw-lab-exec

Trusted by

ecs-tasks.amazonaws.com

Policy

AmazonECSTaskExecutionRolePolicy

Lets tasks

Pull container images and write logs (Fargate and EC2 awsvpcawsvpc
Task network mode that gives each task its own ENI and private IP. Required for ECS Gateway.
Task networking tasks)

Gateway infrastructure role

ECS assumes this infrastructure roleinfrastructure role
IAM role ECS assumes to create and manage ALBs, security groups, ACM certificates, and related ingress resources in your account.
Create a gateway to create ALBs, security groups, ACM certificates, and related resources in your account. Attach the AWS managed policy AmazonECSInfrastructureRoleForGatewayHostSharedALB.

Your caller also needs iam:PassRole on this role when running create-gateway (AdministratorAccess includes it).

aws iam create-role \
  --role-name "${NAME}-gateway-infra" \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "ecs.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }]
  }' \
  --query 'Role.RoleName' --output text

aws iam attach-role-policy \
  --role-name "${NAME}-gateway-infra" \
  --policy-arn arn:aws:iam::aws:policy/AmazonECSInfrastructureRoleForGatewayHostSharedALB

GATEWAY_INFRA_ROLE_ARN=$(aws iam get-role \
  --role-name "${NAME}-gateway-infra" \
  --query Role.Arn --output text)
export GATEWAY_INFRA_ROLE_ARN
echo "gateway infra role ready: ${NAME}-gateway-infra"

Do not paste role ARNs into docs or tickets — they embed the account ID. Keep $GATEWAY_INFRA_ROLE_ARN in your shell for later pages.

Note

IAM is eventually consistent. If create-gateway fails with an assume-role error, wait about a minute and retry.

Task execution role

Both Fargate and EC2 awsvpc tasks use this role to pull images and write logs (CreateLogStream / PutLogEvents). It does not include logs:CreateLogGroup — each path’s services page creates the log group with your caller identity. Your caller also needs iam:PassRole on this role when registering task definitions / creating services.

aws iam create-role \
  --role-name "${NAME}-exec" \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "ecs-tasks.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }]
  }' \
  --query 'Role.RoleName' --output text

aws iam attach-role-policy \
  --role-name "${NAME}-exec" \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

EXEC_ROLE_ARN=$(aws iam get-role \
  --role-name "${NAME}-exec" \
  --query Role.Arn --output text)
export EXEC_ROLE_ARN
echo "task execution role ready: ${NAME}-exec"

Next

Choose a path