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 the following:

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

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

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 destination account's IAM role.
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: 1111222233334444
• A destination account that includes the IAM role, such as destination-account-role, that the Amazon ECS task assumes: 5555666677778888

Configure the IAM role in the source account

Add the following policy statement to your Amazon ECS task role to allow the role to assume the IAM role in the destination account:

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

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.

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

Add the following policy statement to your cross-account IAM role's (destination-account-role) trust policy in the destination account:

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

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.

Create the task definition

Create a task definition file similar to the following:

{
  "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"
}

Note: For taskRoleArn, use the ARN of the source account's IAM role.

To register the task definition, run the following command to example-task-def.json file"

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

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

After the preceding steps, use the AWS CLI to run a standalone task to assume an IAM role on the destination account. Or, you can use the credential_source settings in the config file. Specify where the AWS CLI can find credentials to assume the IAM role attached to the ECS container. For more information, see Assume role credential provider.

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

1. Use the task definition that you created to run the task:
   If you are running the task on Amazon Elastic Compute Cloud (Amazon EC2), then use the docker exec command to perform the testing.
   If you are running the task on AWS Fargate, then use ECS Exec 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 the preceding example, then the ECS task in account 1111222233334444 can assume the IAM role in account 5555666677778888. The ECS task can assume the IAM role to list the ECS cluster resources.

Related information

Amazon ECS task role

IAM tutorial: Delegate access across AWS accounts using IAM roles

AWS SDKs and Tools Reference Guide

Use an IAM role in the AWS CLI