This whitepaper is for historical reference only. Some content might be outdated and some links might not be available.

Authenticating with AWS services

Amazon ECS provides multiple levels to secure your applications and clusters using IAM while containerized applications interact with other AWS services. The following diagram depicts the types of roles Amazon ECS supports when using the EC2 launch type.

Service-linked role

There are multiple activities that the Amazon ECS runs while it orchestrates your container workloads. Amazon ECS uses a service-linked role for the permissions it requires to call other AWS services on your behalf. These include services such as Amazon EC2 to manage elastic network interfaces, ELB to manage targets, and Amazon Route 53 for creating health checks. A more detailed list can be found on the Service-linked role for Amazon ECS page.

Container instance role

The container instance role is the IAM role used as the Instance role by EC2 instances running your containers. This role is also used by the Amazon ECS container agent to make calls to AWS services and connect with the Amazon ECS to register container instances, report status, and get commands. Other examples include the agent starting a telemetry session, or creating the Amazon ECS cluster if one does not already exist. A more detailed list can be found on the Amazon ECS container instance IAM role page.

Task execution role

The task execution role grants the Amazon ECS container agent permission to make AWS API calls on your behalf when an Amazon ECS task is started. An example of an activity that the Amazon ECS Agent runs during this time is pulling container images from a private repository, and private registry authentication needs to be configured.

Another use case where this role is required is injecting sensitive data into your containers. You might choose to store sensitive data (such as database connection strings) in either AWS Secrets Manager or AWS Systems Manager Parameter Store, and reference them in your container definition. Sensitive data is injected into your container as environment variables when the container is initially started without having to write code to retrieve the values.

If the secret or Parameter Store parameter is subsequently updated or rotated, the container will not receive the updated value automatically. Either launch a new task, or if your task is part of a service, you can update the service and use the Force new deployment option to force the service to launch a fresh task.

For Windows tasks that are configured to use the awslogs logging driver, set the ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE environment variable on your container instance. This can be done with user data using the following syntax:

<PowerShell>
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster '<cluster name>' -LoggingDrivers '["json-file","awslogs"]' -EnableTaskIAMRole
</PowerShell>

Task role

The task role is the IAM role assigned to the Containers instances created as part of the Amazon ECS task. This role provides applications using the AWS SDK or CLI the AWS credentials used to make API requests to authorized AWS services. For example, you can set the policy associated with the task role to allow your application to read/write items from or to DynamoDB, publish an event to an EventBridge bus, or start an AWS Step Functions workflow.

One of the requirements that must be met to enable IAM roles for tasks on Windows is that the EnableTaskIAMRole option be set when you launch an EC2 instance. This can be done by using a user data script. For example:

<PowerShell>
Import-Module ECSTools
Initialize-ECSAgent -Cluster '<cluster name>' -EnableTaskIAMRole
</PowerShell>

Additionally, before containers can access the credential proxy on the container instance to get credentials, the container instance must be bootstrapped with the required networking commands. The following code example script should be run on your containers when they start.

$gateway = (Get-NetRoute | Where { $_.DestinationPrefix -eq '0.0.0.0/0' } | Sort-Object RouteMetric | Select NextHop).NextHop
$ifIndex = (Get-NetAdapter -InterfaceDescription "Hyper-V Virtual Ethernet*" | Sort-Object | Select ifIndex).ifIndex
New-NetRoute -DestinationPrefix 169.254.170.2/32 -InterfaceIndex $ifIndex -NextHop $gateway # credentials API
New-NetRoute -DestinationPrefix 169.254.169.254/32 -InterfaceIndex $ifIndex -NextHop $gateway # metadata API

For a complete list of requirements, refer to the Windows IAM roles for tasks page on the Amazon ECS Developer Guide.

Now that you know how to enable IAM roles for Amazon ECS Tasks on Windows, learn how your application code can assume the role.