Task IAM role
Your Amazon ECS tasks can have an IAM role associated with them. The permissions granted in the IAM role are assumed by the containers running in the task. For the IAM permissions that Amazon ECS needs to pull container images and run the task, see Amazon ECS task execution IAM role.
If your containerized applications need to call AWS APIs, they must sign their AWS API
requests with AWS credentials, and a task IAM role provides a strategy for managing
credentials for your applications to use, similar to the way that an Amazon EC2 instance profile
provides credentials to Amazon EC2 instances. Instead of creating and distributing your AWS
credentials to the containers or using the Amazon EC2 instance’s role, you can associate an IAM
role with an Amazon ECS task definition or RunTask
API operation. Your containers
can then use the AWS SDK or AWS CLI to make API requests to authorized AWS
services.
The following explain the benefits of using IAM roles with your tasks.
-
Credential Isolation: A container can only retrieve credentials for the IAM role that is defined in the task definition to which it belongs; a container never has access to credentials that are intended for another container that belongs to another task.
-
Authorization: Unauthorized containers cannot access IAM role credentials defined for other tasks.
-
Auditability: Access and event logging is available through CloudTrail to ensure retrospective auditing. Task credentials have a context of
taskArn
that is attached to the session, so CloudTrail logs show which task is using which role.
Note
When you specify an IAM role for a task, the AWS CLI or other SDKs in the containers for that task use the AWS credentials provided by the task role exclusively and they no longer inherit any IAM permissions from the Amazon EC2 or external instance they are running on.
You can specify a task IAM role in your task definitions, or you can use a
taskRoleArn
override when running a task manually with the
RunTask
API operation. The Amazon ECS agent receives a payload message for
starting the task with additional fields that contain the role credentials. The Amazon ECS agent
sets a unique task credential ID as an identification token and updates its internal
credential cache so that the identification token for the task points to the role
credentials that are received in the payload. The Amazon ECS agent populates the
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
environment variable in the
Env
object (available with the docker inspect
container_id
command) for all containers that
belong to this task with the following relative URI:
/
.credential_provider_version
/credentials?id=task_credential_id
From inside the container, you can query the credential endpoint with the following command:
curl 169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
Output:
{
"AccessKeyId": "ACCESS_KEY_ID
",
"Expiration": "EXPIRATION_DATE
",
"RoleArn": "TASK_ROLE_ARN
",
"SecretAccessKey": "SECRET_ACCESS_KEY
",
"Token": "SECURITY_TOKEN_STRING
"
}
If your Amazon EC2 instance is using at least version 1.11.0
of the container
agent and a supported version of the AWS CLI or SDKs, then the SDK client will see that the
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
variable is available, and it will
use the provided credentials to make calls to the AWS APIs. For more information, see
Using task IAM roles on your Amazon EC2 or external
instances.
Each time the credential provider is used, the request is logged locally on the host
container instance at
/var/log/ecs/audit.log.
.
For more information, see IAM Roles for Tasks Credential Audit Log.YYYY
-MM
-DD
-HH
Considerations for tasks hosted on Amazon EC2 instances
When using an IAM role with your tasks that are running on Amazon EC2 instances, the
containers aren't prevented from accessing the credentials that are supplied to the
Amazon EC2 instance profile (through the Amazon EC2 instance metadata server). We recommend that
you limit the permissions in your container instance role to the minimal list of
permissions used in the AmazonEC2ContainerServiceforEC2Role
managed IAM
policy. For more information, see Amazon ECS container instance IAM role.
The following should also be considered when using a task IAM role for tasks hosted on Amazon EC2 instances.
-
To prevent containers run by tasks that use the
awsvpc
network mode from accessing the credential information supplied to the Amazon EC2 instance profile, while still allowing the permissions that are provided by the task role, set theECS_AWSVPC_BLOCK_IMDS
agent configuration variable totrue
in the agent configuration file and restart the agent. For more information, see Amazon ECS container agent configuration. -
To prevent containers run by tasks that use the
bridge
network mode from accessing the credential information supplied to the Amazon EC2 instance profile, while still allowing the permissions that are provided by the task role, by running the following iptables command on your Amazon EC2 instances. This command doesn't affect containers in tasks that use thehost
orawsvpc
network modes. For more information, see Network mode.sudo yum install -y iptables-services; sudo iptables --insert DOCKER-USER 1 --in-interface docker+ --destination 169.254.169.254/32 --jump DROP
You must save this iptables rule on your Amazon EC2 instance for it to survive a reboot. When using the Amazon ECS-optimized AMI, you can use the following command. For other operating systems, consult the documentation for that operating system.
sudo iptables-save | sudo tee /etc/sysconfig/iptables && sudo systemctl enable --now iptables
Using task IAM roles on your Amazon EC2 or external instances
Your Amazon EC2 or external instances require at least version 1.11.0
of the
container agent to use task IAM roles; however, we recommend using the latest
container agent version. For information about checking your agent version and updating
to the latest version, see Updating the Amazon ECS container agent. If you are using an Amazon ECS-optimized AMI, your
instance needs at least 1.11.0-1
of the ecs-init
package. If
your instances are using the latest Amazon ECS-optimized AMI, then they contain the required
versions of the container agent and ecs-init
. For more information, see
Amazon ECS-optimized AMI.
If you are not using the Amazon ECS-optimized AMI for your container instances, be sure to
add the --net=host
option to your docker run command
that starts the agent and the following agent configuration variables for your desired
configuration (for more information, see Amazon ECS container agent configuration):
ECS_ENABLE_TASK_IAM_ROLE=true
-
Uses IAM roles for tasks for containers with the
bridge
anddefault
network modes. ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true
-
Uses IAM roles for tasks for containers with the
host
network mode. This variable is only supported on agent versions 1.12.0 and later.
For an example run command, see Manually updating the Amazon ECS container agent (for non-Amazon ECS-Optimized AMIs). You will also need to set the following networking commands on your container instance so that the containers in your tasks can retrieve their AWS credentials:
sudo sysctl -w net.ipv4.conf.all.route_localnet=1
sudo iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679
sudo iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679
You must save these iptables rules on your container instance for them to survive a reboot. You can use the iptables-save and iptables-restore commands to save your iptables rules and restore them at boot. For more information, consult your specific operating system documentation.
Creating an IAM role and policy for your tasks
When creating an IAM policy for your tasks to use, the policy should include the permissions that you would like the containers in your tasks to assume. You can use an existing AWS managed policy, or you can create a custom policy from scratch that meets your specific needs. For more information, see Creating IAM policies in the IAM User Guide.
Important
For Amazon ECS tasks (for all launch types), we recommend that you use the IAM policy
and role for your tasks. These credentials allow your task to make AWS API
requests without calling sts:AssumeRole
to assume the same role that is
already associated with the task. If your task requires that a role assumes itself,
you must create a trust policy that explicitly allows that role to assume itself.
For more information, see Modifying a role trust policy in the IAM User Guide.
After the IAM policy is created, you can create an IAM role which includes that policy which you reference in your Amazon ECS task definition. You can create the role using the Elastic Container Service Task use case in the IAM console. Then, you can attach your specific IAM policy to the role that gives the containers in your task the permissions you desire. The procedures below describe how to do this.
If you have multiple task definitions or services that require IAM permissions, you should consider creating a role for each specific task definition or service with the minimum required permissions for the tasks to operate so that you can minimize the access that you provide for each task.
For information about the service endpoint for your Region, see Service endpoints in the Amazon Web Services General Reference Reference Guide.
The IAM task role must have a trust policy that specifies the
ecs-tasks.amazonaws.com
service. The sts:AssumeRole
permission allows your tasks to assume an IAM role that's different from the one that
the Amazon EC2 instance uses. This way, your task doesn't inherit the role associated with
the Amazon EC2 instance. The following is an example trust policy. Replace the Region
identifier and specify the AWS account number that you use when launching
tasks.
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "ecs-tasks.amazonaws.com" ] }, "Action":"sts:AssumeRole", "Condition":{ "ArnLike":{ "aws:SourceArn":"arn:aws:ecs:
us-west-2
:111122223333
:*" }, "StringEquals":{ "aws:SourceAccount":"111122223333
" } } } ] }
Important
When creating your task IAM role, it is recommended that you use the
aws:SourceAccount
or aws:SourceArn
condition keys in
either the trust relationship or the IAM policy associated with the role to scope
the permissions further to prevent the confused deputy security issue. Using the
aws:SourceArn
condition key to specify a specific cluster is not
currently supported, you should use the wildcard to specify all clusters. To learn
more about the confused deputy problem and how to protect your AWS account, see
The
confused deputy problem in the
IAM User Guide.
The following procedures describe how to create a policy to retrieve objects from Amazon S3
with an example policy. Replace all user input
with your own
values.
The following procedures describe how to create a task IAM role by attaching an IAM policy that you create.
IAM permissions required for ECS Exec
The ECS Exec feature requires a task IAM role to grant containers the
permissions needed for communication between the managed SSM agent
(execute-command
agent) and the SSM service. You should add the
following permissions to a task IAM role and include the task IAM role in your task
definition. For more information, see Adding and
Removing IAM Policies in the IAM User Guide.
Use the following policy for your task IAM role to add the required SSM permissions.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" } ] }
Specifying an IAM role for your tasks
After you have created a role and attached a policy to that role, you can run tasks that assume the role. You have several options to do this:
-
Specify an IAM role for your tasks in the task definition. You can create a new task definition or a new revision of an existing task definition and specify the role you created previously. If you use the console to create your task definition, choose your IAM role in the Task Role field. For more information, see Creating a task definition using the console.
If you use the AWS CLI or SDKs, specify the Amazon Resource Name (ARN) of your task role using the
taskRoleArn
parameter. For more information, see TaskDefinition in the Amazon ECS API Reference and Task definition parameters.Note
This option is required if you want to use IAM task roles in an Amazon ECS service.
-
Specify an IAM task role override when running a task. You can specify an IAM task role override when running a task. If you use the AWS CLI or SDKs, specify your task role ARN using the
taskRoleArn
parameter in theoverrides
JSON object. For more information, about theoverrides
parameter, see RunTask and TaskOverride in the Amazon ECS API Reference. For more information about overriding using the console, see Run an application as an Amazon ECS task.
Note
In addition to the standard Amazon ECS permissions required to run tasks and services,
users also require iam:PassRole
permissions to use IAM roles for
tasks.