Amazon ECS instance role - Amazon Batch
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 instance role

Amazon Batch compute environments are populated with Amazon ECS container instances. They run the Amazon ECS container agent locally. The Amazon ECS container agent makes calls to various Amazon API operations on your behalf. Therefore, container instances that run the agent require an IAM policy and role for these services to recognize that the agent belongs to you. You must create an IAM role and an instance profile for the container instances to use when they're launched. Otherwise, you can't create a compute environment and launch container instances into it. This requirement applies to container instances launched with or without the Amazon ECS optimized AMI provided by Amazon. For more information, see Amazon ECS container instance IAM role in the Amazon Elastic Container Service Developer Guide.

The Amazon ECS instance role and instance profile are automatically created for you in the console first-run experience. However, you can follow these steps to check if your account already has the Amazon ECS instance role and instance profile. The following steps also cover how to attach the managed IAM policy.

To check for the ecsInstanceRole in the IAM console
  1. Open the IAM console at

  2. In the navigation pane, choose Roles.

  3. Search the list of roles for ecsInstanceRole. If the role doesn't exist, use the following steps to create the role.

    1. Choose Create Role.

    2. For Trusted entity type, choose Amazon Web Service.

    3. For Common use cases, choose EC2.

    4. Choose Next.

    5. For Permissions policies, search for AmazonEC2ContainerServiceforEC2Role.

    6. Choose the check box next to AmazonEC2ContainerServiceforEC2Role, then choose Next.

    7. For Role Name, type ecsInstanceRole and choose Create Role.


      If you use the Amazon Web Services Management Console to create a role for Amazon EC2, the console creates an instance profile with the same name as the role.

Alternatively, you can use the Amazon CLI to create the ecsInstanceRole IAM role. The following example creates an IAM role with a trust policy and an Amazon managed policy.

To create an IAM role and instance profile (Amazon CLI)
  1. Create the following trust policy and save it in a text file that's named ecsInstanceRole-role-trust-policy.json.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": ""}, "Action": "sts:AssumeRole" } ] }
  2. Use the create-role command to create the ecsInstanceRole role. Specify the trust policy file location in the assume-role-policy-document parameter.

    $ aws iam create-role \ --role-name ecsInstanceRole \ --assume-role-policy-document file://ecsInstanceRole-role-trust-policy.json

    The following is an example response.

    { "Role": { "Path": "/", "RoleName: "ecsInstanceRole", "RoleId": "AROAT46P5RDIY4EXAMPLE", "Arn": "arn:aws-cn:iam::123456789012:role/ecsInstanceRole". "CreateDate": "2022-12-12T23:46:37.247Z", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service: "" } "Action": "sts:AssumeRole", } ] } }
  3. Use the create-instance-profile command to create an instance profile that's named ecsInstanceRole.


    You need to create roles and instance profiles as separate actions in the Amazon CLI and Amazon API.

    $ aws iam create-instance-profile --instance-profile-name ecsInstanceRole

    The following is an example response.

    { "InstanceProfile": { "Path": "/", "InstanceProfileName": "ecsInstanceRole", "InstanceProfileId": "AIPAT46P5RDITREXAMPLE", "Arn": "arn:aws-cn:iam::123456789012:instance-profile/ecsInstanceRole", "CreateDate": "2022-06-30T23:53:34.093Z", "Roles": [], } }
  4. Use the add-role-to-instance-profile command to add the ecsInstanceRole role to the ecsInstanceRole instance profile.

    aws iam add-role-to-instance-profile \ --role-name ecsInstanceRole --instance-profile-name ecsInstanceRole
  5. Use the attach-role-policy command to attach the AmazonEC2ContainerServiceforEC2Role Amazon managed policy to the ecsInstanceRole role.

    $ aws iam attach-role-policy \ --policy-arn arn:aws-cn:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role \ --role-name ecsInstanceRole