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).

Best practices for IAM roles in Amazon ECS

We recommend that you assign a task role. Its role can be distinguished from the role of the Amazon EC2 instance that it's running on. Assigning each task a role aligns with the principle of least privileged access and allows for greater granular control over actions and resources.

When assigning IAM roles for a task, you must use the following trust policy so that each of your tasks can assume an IAM role that's different from the one that your EC2 instance uses. This way, your task doesn't inherit the role of your EC2 instance.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

When you add a task role to a task definition, the Amazon ECS container agent automatically creates a token with a unique credential ID (for example, 12345678-90ab-cdef-1234-567890abcdef) for the task. This token and the role credentials are then added to the agent's internal cache. The agent populates the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI in the container with the URI of the credential ID (for example, /v2/credentials/12345678-90ab-cdef-1234-567890abcdef).

You can manually retrieve the temporary role credentials from inside a container by appending the environment variable to the IP address of the Amazon ECS container agent and running the curl command on the resulting string.

curl 169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

The expected output is as follows:

{
	"RoleArn": "arn:aws:iam::123456789012:role/SSMTaskRole-SSMFargateTaskIAMRole-DASWWSF2WGD6",
	"AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
	"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
	"Token": "IQoJb3JpZ2luX2VjEEM/Example==",
	"Expiration": "2021-01-16T00:51:53Z"
}

Newer versions of the Amazon SDKs automatically fetch these credentials from the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable when making Amazon API calls. For information about how to renew credentials, see Renewing Amazon credentials on rePost.

The output includes an access key-pair consisting of a secret access key ID and a secret key which your application uses to access Amazon resources. It also includes a token that Amazon uses to verify that the credentials are valid. By default, credentials assigned to tasks using task roles are valid for six hours. After that, they are automatically rotated by the Amazon ECS container agent.

Task execution role

The task execution role is used to grant the Amazon ECS container agent permission to call specific Amazon API actions on your behalf. For example, when you use Amazon Fargate, Fargate needs an IAM role that allows it to pull images from Amazon ECR and write logs to CloudWatch Logs. An IAM role is also required when a task references a secret that's stored in Amazon Secrets Manager, such as an image pull secret.

Container instance role

The AmazonEC2ContainerServiceforEC2Role managed IAM policy includes the following permissions. Following the standard security advice of granting least privilege, the AmazonEC2ContainerServiceforEC2Role managed policy can be used as a guide. If you don't need any of the permissions that are granted in the managed policy for your use case, create a custom policy and add only the permissions that you need.

The following policy contains the required permissions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DiscoverPollEndpoint",
                "ecs:Poll",
                "ecs:RegisterContainerInstance",
                "ecs:UpdateContainerInstancesState",
                "ecs:Submit*"
            ],
            "Resource": "*"
        }
    ]
}

Service-linked roles

You can use the service-linked role for Amazon ECS to grant the Amazon ECS service permission to call other service APIs on your behalf. Amazon ECS needs the permissions to create and delete network interfaces, register, and de-register targets with a target group. It also needs the necessary permissions to create and delete scaling policies. These permissions are granted through the service-linked role. This role is created on your behalf the first time that you use the service.

Roles recommendations

We recommend that you do the following when setting up your task IAM roles and policies.

Block access to Amazon EC2 metadata

When you run your tasks on Amazon EC2 instances, we strongly recommend that you block access to Amazon EC2 metadata to prevent your containers from inheriting the role assigned to those instances. If your applications have to call an Amazon API action, use IAM roles for tasks instead.

To prevent tasks running in bridge mode from accessing Amazon EC2 metadata, run the following command or update the instance's user data. For more instruction on updating the user data of an instance, see this Amazon Support Article. For more information about the task definition bridge mode, see task definition network mode.

sudo yum install -y iptables-services; sudo iptables --insert FORWARD 1 --in-interface docker+ --destination 169.254.169.254/32 --jump DROP

For this change to persist after a reboot, run the following command that's specific for your Amazon Machine Image (AMI):

For tasks that use awsvpc network mode, set the environment variable ECS_AWSVPC_BLOCK_IMDS to true in the /etc/ecs/ecs.config file.

You should set the ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST variable to false in the ecs-agent config file to prevent the containers that are running within the host network from accessing the Amazon EC2 metadata.

Use the awsvpc network mode

Use the network awsvpc network mode to restrict the flow of traffic between different tasks or between your tasks and other services that run within your Amazon VPC. This adds an additional layer of security. The awsvpc network mode provides task-level network isolation for tasks that run on Amazon EC2. It is the default mode on Amazon Fargate. it's the only network mode that you can use to assign a security group to tasks.

Use IAM Access Advisor to refine roles

We recommend that you remove any actions that were never used or haven't been used for some time. This prevents unwanted access from happening. To do this, review the results produced by IAM Access Advisor, and then remove actions that were never used or haven't been used recently. You can do this by following the following steps.

Run the following command to generate a report showing the last access information for the referenced policy:

aws iam generate-service-last-accessed-details --arn arn:aws:iam::123456789012:policy/ExamplePolicy1

use the JobId that was in the output to run the following command. After you do this, you can view the results of the report.

aws iam get-service-last-accessed-details --job-id 98a765b4-3cde-2101-2345-example678f9

For more information, see IAM Access Advisor.

Monitor Amazon CloudTrail for suspicious activity

You can monitor Amazon CloudTrail for any suspicious activity. Most Amazon API calls are logged to Amazon CloudTrail as events. They are analyzed by Amazon CloudTrail Insights, and you're alerted of any suspicious behavior that's associated with write API calls. This might include a spike in call volume. These alerts include such information as the time the unusual activity occurred and the top identity ARN that contributed to the APIs.

You can identify actions that are performed by tasks with an IAM role in Amazon CloudTrail by looking at the event's userIdentity property. In the following example, the arn includes of the name of the assumed role, s3-write-go-bucket-role, followed by the name of the task, 7e9894e088ad416eb5cab92afExample.

"userIdentity": {
    "type": "AssumedRole",
    "principalId": "AROA36C6WWEJ2YEXAMPLE:7e9894e088ad416eb5cab92afExample",
    "arn": "arn:aws:sts::123456789012:assumed-role/s3-write-go-bucket-role/7e9894e088ad416eb5cab92afExample",
    ...
}