Amazon ECS Anywhere IAM role - Amazon Elastic Container Service
Creating the Amazon ECS Anywhere role
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon ECS Anywhere IAM role

When you register an on-premises server or virtual machine (VM) to your cluster, the server or VM requires an IAM role to communicate with Amazon APIs. You only need to create this IAM role once for each Amazon account. However, this IAM role must be associated with each server or VM that you register to a cluster. This role is the ECSAnywhereRole. You can create this role manually. Alternatively, Amazon ECS can create the role on your behalf when you register an external instance in the Amazon Web Services Management Console. You can use IAM console search to search for ecsAnywhereRole and see if your account already has the role. For more information, see IAM console search in the IAM user guide.

Amazon provides two managed IAM policies that can be used when creating the ECS Anywhere IAM role, the AmazonSSMManagedInstanceCore and AmazonEC2ContainerServiceforEC2Role policies. The AmazonEC2ContainerServiceforEC2Role policy includes permissions that likely provide more access than you need. Therefore, depending on your specific use case, we recommend that you create a custom policy adding only the permissions from that policy that you require in it. For more information, see Amazon ECS container instance IAM role.

The task execution IAM role grants the Amazon ECS container agent permission to make Amazon API calls on your behalf. When a task execution IAM role is used, it must be specified in your task definition. For more information, see Amazon ECS task execution IAM role.

The task execution role is required if any of the following conditions apply:

  • You're sending container logs to CloudWatch Logs using the awslogs log driver.

  • Your task definition specifies a container image that's hosted in an Amazon ECR private repository. However, if the ECSAnywhereRole role that's associated with your external instance also includes the permissions necessary to pull images from Amazon ECR then your task execution role doesn't need to include them.

Creating the Amazon ECS Anywhere role

Replace all user input with your own information.

  1. Create a local file named ssm-trust-policy.json with the following trust policy.

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

  2. Create the role and attach the trust policy by using the following Amazon CLI command.

    aws iam create-role --role-name ecsAnywhereRole --assume-role-policy-document file://ssm-trust-policy.json

  3. Attach the Amazon managed policies by using the following command.

    aws iam attach-role-policy --role-name ecsAnywhereRole --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
aws iam attach-role-policy --role-name ecsAnywhereRole --policy-arn arn:aws-cn:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role

You can also use the IAM custom trust policy workflow to create the role. For more information, see Creating a role using custom trust policies (console) in the IAM User Guide.