When configuring Amazon ECS, you'll encounter two critical IAM roles that often cause confusion:

• ECS Container Instance Role - Applied to EC2 instances hosting your containers
• ECS Task Execution Role - Assigned to tasks at runtime

This role must be attached to your EC2 instances before they can register with ECS. The minimal required permissions include:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateCluster",
        "ecs:DeregisterContainerInstance",
        "ecs:DiscoverPollEndpoint",
        "ecs:Poll",
        "ecs:RegisterContainerInstance",
        "ecs:StartTelemetrySession",
        "ecs:Submit*"
      ],
      "Resource": "*"
    }
  ]
}

This role allows your containers to make AWS API calls. Common scenarios requiring this role:

• Pulling images from ECR
• Writing logs to CloudWatch
• Accessing secrets from Secrets Manager

Example policy for basic ECR access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }
  ]
}

If your tasks fail to start, verify these common misconfigurations:

1. The ECS agent can't register the instance - check instance role permissions
2. Containers can't pull images - verify task execution role has ECR permissions
3. Tasks timeout during launch - ensure both roles exist in the same region

Here's a complete CloudFormation snippet setting up both roles:

Resources:
  ECSInstanceRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Principal:
            Service: [ec2.amazonaws.com]
          Action: ['sts:AssumeRole']
      Path: /
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role

  TaskExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Principal:
            Service: [ecs-tasks.amazonaws.com]
          Action: ['sts:AssumeRole']
      Path: /
      Policies:
        - PolicyName: ecs-task-execution
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - ecr:GetAuthorizationToken
                  - ecr:BatchCheckLayerAvailability
                  - ecr:GetDownloadUrlForLayer
                  - ecr:BatchGetImage
                  - logs:CreateLogStream
                  - logs:PutLogEvents
                Resource: '*'

When deploying Amazon ECS, you'll primarily need to configure two critical IAM roles:

1. ecsInstanceRole (for ECS container instances)
2. ecsTaskExecutionRole (for task execution)

The ecsInstanceRole grants permissions to your container instances to:

• Register with ECS clusters
• Pull container images from ECR
• Publish container logs to CloudWatch

Example policy document:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:RegisterContainerInstance",
        "ecs:DeregisterContainerInstance",
        "ecs:DiscoverPollEndpoint",
        "ecs:Submit*",
        "ecs:Poll",
        "ecs:StartTelemetrySession"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

The ecsTaskExecutionRole enables your tasks to:

• Pull images from private repositories
• Use AWS Secrets Manager/Parameter Store
• Write logs to CloudWatch

Example task role policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Frequent issues include:

• Missing ECR permissions for image pulling
• Insufficient CloudWatch Logs permissions
• Network interface creation permissions when using awsvpc network mode

Remember that:

Task Execution Role = What the ECS service needs to RUN your task
Task Role = What your APPLICATION needs to DO during execution

Example task role for S3 access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::your-bucket/*"
    }
  ]
}

1. Verify both roles exist and are properly attached
2. Check trust relationships for both roles
3. Validate network permissions if using awsvpc
4. Confirm ECR repository policies allow access