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 Required IAM permissions for external instances.
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.
Checking for the container instance
( ecsInstanceRole
) in the IAM console
The Amazon ECS instance role is automatically created for you when completing the Amazon ECS console first-run experience. However, 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 check and see if your account already has the Amazon ECS container instance IAM role and to attach the managed IAM policy if needed.
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.
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane, choose Roles.
-
In the search box, enter
ecsInstanceRole
. If the role does exist, choose the role to view the attached policies. -
On the Permissions tab, verify that the AmazonEC2ContainerServiceforEC2Role is attached to the role.
-
Choose Add Permissions, Attach policies.
-
To narrow the available policies to attach, for Filter, enter AmazonEC2ContainerServiceforEC2Role.
-
Check the box to the left of the AmazonEC2ContainerServiceforEC2Role policy, and then choose Attach policy.
-
-
Choose Trust relationships.
-
Verify that the trust relationship contains the following policy. If the trust relationship matches the policy below, choose Cancel. If the trust relationship does not match, choose Edit trust policy, copy the policy into the Policy Document window and choose Update policy.
{ "Version": "2008-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
Creating the container instance ( ecsInstanceRole
)
role
Important
If you are registering external instances to your cluster, see Required IAM permissions for external instances.
The Amazon ECS instance role is automatically created for you when completing the Amazon ECS console first-run experience. However, 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 check and see if your account already has the Amazon ECS container instance IAM role and to attach the managed IAM policy if needed.
To create the ecsInstanceRole
IAM role for your container
instances
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane, choose Roles, and then choose Create role.
-
Choose the Amazon service role type, and then choose Elastic Container Service.
-
Choose the EC2 Role for Elastic Container Service use case, and then choose Next: Permissions.
-
In the Permissions policies section, verify the AmazonEC2ContainerServiceforEC2Role policy is selected, and then choose Next.
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.
-
For Role name, enter ecsInstanceRole and optionally you can enter a description.
-
For Add tags (optional), enter any custom tags to associate with the policy, and then choose Next: Review.
-
Review your role information and then choose Create role to finish.
To create the ecsInstanceRole
role (Amazon CLI)
-
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" } }
-
Add the
ecsInstanceRole
role to theecsInstanceRole-profile
instance profile.aws iam add-role-to-instance-profile \ --instance-profile-name ecsInstanceRole-profile \ --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.
To allow Amazon S3 read-only access for your container instance role
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the navigation pane, choose Policies.
-
In the Filter policies search box, enter AmazonS3ReadOnlyAccess, and then choose the policy.
Note
This policy allows read-only access to all Amazon S3 resources. For more restrictive bucket policy examples, see Bucket Policy Examples in the Amazon Simple Storage Service User Guide.
-
Choose Attach.
-
In the Filter roles search box, enter ecsInstanceRole.
-
Check the box to the left of the ecsInstanceRole role, and then choose Attach policy.