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 AWS CLI commands.
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 AWS 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
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.
- AWS Management Console
To create the ecsInstanceRole
IAM role for your container
instances
Open the IAM console at
https://console.aws.amazon.com/iam/.
-
In the navigation pane, choose Roles, and then choose
Create role.
-
Choose the AWS service role type, and then under
Use cases for other AWS services, 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.
The AmazonEC2ContainerServiceforEC2Role managed policy
should be attached to the container instance IAM role, otherwise you will
receive an error using the AWS 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.
- AWS CLI
-
Replace all user input
with your own
values.
-
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"
}
]
}
-
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
-
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:iam::123456789012:instance-profile/ecsInstanceRole-profile"
}
}
-
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
-
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 AWS 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 AWS 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::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 AWS 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
.
- AWS Management Console
-
To use the JSON policy editor to create a policy
Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
-
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.
-
At the top of the page, choose Create policy.
-
In the Policy editor section, choose the
JSON option.
-
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:*:*:*"]
}
]
}
-
Choose Next.
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.
-
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.
-
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 AWS Identity and Access Management User Guide.
- AWS CLI
-
-
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:*:*:*"]
}
]
}
-
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
-
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'
-
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:iam:111122223333:aws:policy/cwlogspolicy