Amazon ECS container instance IAM role - Amazon Elastic Container Service
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 container instance IAM role

Amazon ECS container instances, including both Amazon EC2 and external instances, run the Amazon ECS container agent and require an IAM role for the service to know that the agent belongs to you. Before you launch container instances and register them to a cluster, you must create an IAM role for your container instances to use. The role is created in the account that you use to log into the console or run the Amazon CLI commands.

Important

If you are registering external instances to your cluster, the IAM role you use requires Systems Manager permissions as well. For more information, see ECS Anywhere IAM role.

Amazon ECS provides the AmazonEC2ContainerServiceforEC2Role managed IAM policy which contains the permissions needed to use the full Amazon ECS feature set. This managed policy can be attached to an IAM role and associated with your container instances. Alternatively, you can use the managed policy as a guide when creating a custom policy to use. The container instance role provides permissions needed for the Amazon ECS container agent and Docker daemon to call Amazon APIs on your behalf. For more information on the managed policy, see AmazonEC2ContainerServiceforEC2Role.

Amazon ECS supports launching container instances with increased ENI density using supported Amazon EC2 instance types. When you use this feature, we recommend that you create 2 container instance roles. Enable the awsvpcTrunking account setting for one role and use that role for tasks that require ENI trunking. For information about the awsvpcTrunking account setting, see Accessing Amazon ECS features through account settings.

Creating the container instance ( ecsInstanceRole) role

Important

If you are registering external instances to your cluster, see ECS Anywhere IAM role.

You can manually create the role and attach the managed IAM policy for container instances to allow Amazon ECS to add permissions for future features and enhancements as they are introduced. Use the following procedure to attach the managed IAM policy if needed.

Amazon Web Services Management Console
To create the service role for Elastic Container Service (IAM console)
  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane of the IAM console, choose Roles, and then choose Create role.

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

  4. For Service or use case, choose Elastic Container Service, and then choose the EC2 Role for Elastic Container Service use case.

  5. Choose Next.

  6. In the Permissions policies section, verify that the AmazonEC2ContainerServiceforEC2Role policy is selected.

    Important

    The AmazonEC2ContainerServiceforEC2Role managed policy should be attached to the container instance IAM role, otherwise you will receive an error using the Amazon Web Services Management Console to create clusters.

  7. (Optional) Set a permissions boundary. This is an advanced feature that is available for service roles, but not service-linked roles.

    1. Open the Set permissions boundary section, and then choose Use a permissions boundary to control the maximum role permissions.

      IAM includes a list of the Amazon managed and customer-managed policies in your account.

    2. Select the policy to use for the permissions boundary.

  8. Choose Next.

  9. Enter a role name or a role name suffix to help you identify the purpose of the role.

    Important

    When you name a role, note the following:

    • Role names must be unique within your Amazon Web Services account, and can't be made unique by case.

      For example, don't create roles named both PRODROLE and prodrole. When a role name is used in a policy or as part of an ARN, the role name is case sensitive, however when a role name appears to customers in the console, such as during the sign-in process, the role name is case insensitive.

    • You can't edit the name of the role after it's created because other entities might reference the role.

  10. (Optional) For Description, enter a description for the role.

  11. (Optional) To edit the use cases and permissions for the role, in the Step 1: Select trusted entities or Step 2: Add permissions sections, choose Edit.

  12. (Optional) To help identify, organize, or search for the role, add tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM resources in the IAM User Guide.

  13. Review the role, and then choose Create role.

Amazon CLI

Replace all user input with your own values.

  1. Create a file called instance-role-trust-policy.json with the following contents.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com"}, "Action": "sts:AssumeRole" } ] }
  2. Use the following command to create the instance IAM role using the trust policy document.

    aws iam create-role \ --role-name ecsInstanceRole \ --assume-role-policy-document file://instance-role-trust-policy.json
  3. Create an instance profile named ecsInstanceRole-profile using the create-instance-profile command.

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

    Example response

    { "InstanceProfile": { "InstanceProfileId": "AIPAJTLBPJLEGREXAMPLE", "Roles": [], "CreateDate": "2022-04-12T23:53:34.093Z", "InstanceProfileName": "ecsInstanceRole-profile", "Path": "/", "Arn": "arn:aws-cn:iam::123456789012:instance-profile/ecsInstanceRole-profile" } }
  4. Add the ecsInstanceRole role to the ecsInstanceRole-profile instance profile.

    aws iam add-role-to-instance-profile \ --instance-profile-name ecsInstanceRole-profile \ --role-name ecsInstanceRole
  5. Attach the AmazonEC2ContainerServiceRoleForEC2Role managed policy to the role using the following command.

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

Adding Amazon S3 read-only access to your container instance ( ecsInstanceRole) role

Storing configuration information in a private bucket in Amazon S3 and granting read-only access to your container instance IAM role is a secure and convenient way to allow container instance configuration at launch time. You can store a copy of your ecs.config file in a private bucket, use Amazon EC2 user data to install the Amazon CLI and then copy your configuration information to /etc/ecs/ecs.config when the instance launches.

For more information about creating an ecs.config file, storing it in Amazon S3, and launching instances with this configuration, see Storing container instance configuration in Amazon S3.

You can use the following Amazon CLI command to allow Amazon S3 read-only access for your container instance role. Replace ecsInstanceRole with the name of the role that you created.

aws iam attach-role-policy \ --role-name ecsInstanceRole \ --policy-arn arn:aws-cn::iam::aws:policy/AmazonS3ReadOnlyAccess

You can also use the IAM console to add Amazon S3 read-only access (AmazonS3ReadOnlyAccess) to your role. For more information, see Modifying a role permissions policy (console) in the Amazon Identity and Access Management User Guide.

Required permissions for monitoring container instances

Before your container instances can send log data to CloudWatch Logs, you must create an IAM policy to allow your container instances to use the CloudWatch Logs APIs, and then you must attach that policy to ecsInstanceRole.

Amazon Web Services Management Console
To use the JSON policy editor to create a policy
  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane on the left, choose Policies.

    If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose Get Started.

  3. At the top of the page, choose Create policy.

  4. In the Policy editor section, choose the JSON option.

  5. Enter the following JSON policy document:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Resource": ["arn:aws:logs:*:*:*"] } ] }
  6. Choose Next.

    Note

    You can switch between the Visual and JSON editor options anytime. However, if you make changes or choose Next in the Visual editor, IAM might restructure your policy to optimize it for the visual editor. For more information, see Policy restructuring in the IAM User Guide.

  7. On the Review and create page, enter a Policy name and a Description (optional) for the policy that you are creating. Review Permissions defined in this policy to see the permissions that are granted by your policy.

  8. Choose Create policy to save your new policy.

After you create the policy, attach the policy to the container instance role. For information about how to attach the policy to the role, see Modifying a role permissions policy (console) in the Amazon Identity and Access Management User Guide.

Amazon CLI
  1. Create a file called instance-cw-logs.json with the following content.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Resource": ["arn:aws:logs:*:*:*"] } ] }
  2. Use the following command to create the IAM policy using the JSON policy document file.

    aws iam create-policy \ --policy-name cwlogspolicy \ --policy-document file://instance-cw-logs.json
  3. Retrieve the ARN of the IAM policy you created using the following command. Replace cwlogspolicy with the name of the policy you created.

    aws iam list-policies --scope Local --query 'Policies[?PolicyName==`cwlogsppolicy`].Arn'
  4. Use the following command to attach the policy to the container instance IAM role using the policy ARN.

    aws iam attach-role-policy \ --role-name ecsInstanceRole \ --policy-arn arn:aws-cn:iam:111122223333:aws:policy/cwlogspolicy