How do I configure my Amazon ECS task to assume an IAM role in another AWS account?

Short description

You might set up your Amazon ECS task to assume an IAM role in another account to do either of the following:

• Access resources, such as an Amazon Simple Storage Service (Amazon S3) bucket.
• Perform tasks, such as describing a resource and starting or stopping instances, through API calls.

To allow your Amazon ECS task to assume an IAM role in another AWS account, do the following:

1. Configure an IAM role in the source account.
2. Modify the trust policy of the destination account's IAM role to allow the source account's IAM role to assume the IAM role in the destination account.
3. Create a task definition in the source account, and define the IAM role created in step 1 as the Amazon ECS task role.

Resolution

The examples used in this article reference two different AWS accounts:

• A source account that hosts the Amazon ECS task (example: 1111222233334444)
• A destination account that includes the IAM role (example: destination-account-role) that the Amazon ECS task assumes (example: 5555666677778888)

Configure the IAM role in the source account

Use the instructions in Adding and removing IAM identity permissions to add the following policy statement to your Amazon ECS task role (example: my-ECS-task-role). Doing so allows the ECS task role to assume the IAM role in the destination account.

Note:

• Replace 5555666677778888 with the account ID of the cross-account role that your task needs to assume.
• Replace destination-account-role with the name of the assumed role.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::5555666677778888:role/destination-account-role"
  }
}

Modify the trust policy of the IAM role in the destination account

Use the instructions in Modifying a role trust policy (console) to add the following policy statement to your cross-account IAM role's (destination-account-role) trust policy in the destination account.

Note:

• Replace 1111222233334444 with the account ID of the source account where the ECS task IAM role exists.
• Replace my-ECS-task-role with the name of your ECS IAM task role.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::1111222233334444:role/my-ECS-task-role"
    },
    "Action": "sts:AssumeRole"
  }]
}

Create the task definition

Create a task definition file similar to the following (example-task-def.json), and use the ARN of the source account's IAM role (my-ECS-task-role) for taskRoleArn:

{
  "containerDefinitions": [
    {
      "name": "test",
      "image": "your-test-image",
      "cpu": 100,
      "memory": 200,
      "essential": true
    }
  ],
  "family": "verify-assume-cross-account-role",
  "taskRoleArn": "arn:aws:iam::1111222233334444:role/my-ECS-task-role"
}

Run the following command to register the task definition using the example-task-def.json file:

aws ecs register-task-definition —cli-input-json file://example-task-def.json

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

After completing the preceding steps, you can run a standalone task to assume an IAM role on the destination account using the AWS Command Line Interface (AWS CLI). Or, you can use the credential_source settings in the AWS CLI config file to specify where the AWS CLI can find credentials to assume the IAM role attached to the ECS container. With this setting, the task can assume the role without having to export new credentials. For more information, see Assume role credentials.

Verify that the container within the task can assume the IAM role in the destination account and access the resource

1.    Run the task using the task definition that you created.

• If you are running the task on Amazon Elastic Compute Cloud (Amazon EC2), then use the docker exec command to get into the container to perform the testing.
• If you are running task on AWS Fargate, then use the ECS Exec feature to get into the container to perform the testing.

2.    Configure the AWS CLI config file, and then verify that the task assumes the IAM role in the destination account:

Using the ECS exec command to access the container
$ aws ecs execute-command --cluster example-cluster --task example-taskID --container test --interactive --command "/bin/bash"

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.
Starting session with SessionId: ecs-execute-command-064a40c5149cecc32

# Create AWS CLI config file
bash-4.2# mkdir /root/.aws
bash-4.2# cat <<EOF > /root/.aws/config
[profile cross-account]
role_arn = arn:aws:iam::5555666677778888:role/destination-account-role
credential_source = EcsContainer
EOF

# Check the current task IAM role
bash-4.2# aws sts get-caller-identity
{
  "UserId": "AROA4SHE6JAGEAYNUH6ST:8ee54a7f5c474a3f93ee28474486402f",
  "Account": "1111222233334444",
  "Arn": "arn:aws:sts::1111222233334444:assumed-role/my-ECS-task-role/8ee54a7f5c474a3f93ee28474486402f"
}

# Assume the cross-account IAM role
bash-4.2# aws sts get-caller-identity --profile cross-account
{
  "UserId": "AROA3A44JRHY6FFSMMJKN:botocore-session-1647426859",
  "Account": "5555666677778888",
  "Arn": "arn:aws:sts::5555666677778888:assumed-role/destination-account-role/botocore-session-1647426859"
}

# Verify that you can list the resources in cross-account in the task
bash-4.2# aws ecs list-clusters --profile cross-account
{
  "clusterArns": [
    "arn:aws:ecs:us-east-1:5555666677778888:cluster/default"
  ]
}

If your outputs look similar to those listed, then the ECS task in account 1111222233334444 can assume the IAM role in account 5555666677778888 to list the ECS cluster resources.

---

Related information

IAM roles for tasks

IAM tutorial: Delegate access across AWS accounts using IAM roles

AWS SDKs and tools that use the shared config and credentials files

Credential file settings