How can I allow a secondary account to push or pull images in my Amazon ECR image repository?

4 minute read

I want to allow a secondary account to push or pull images in my Amazon Elastic Container Registry (Amazon ECR) image repository.


You can push or pull images to or from an Amazon ECR repository in another account. First, you must create a policy that allows the secondary account to perform API calls against the repository. Then, use a Docker authentication token generated from the secondary account to use push and pull commands against the primary account's repository.

Create a policy that allows the secondary account to perform API calls against the image repository

1.    Open the Amazon ECR console for your primary account.

2.    Choose the hyperlinked Repository name of the repository that you want to modify.

3.    From the left navigation pane, under Amazon ECR - Repositories, choose Permissions.

4.    To add a repository policy for your secondary account from within your primary account, choose Edit policy JSON. Enter your policy into the code editor, and then choose Save.

Important: In your policy, include the account number of the secondary account and the actions that the account can perform against the repository. To allow access to a specific role, provide the role arn as the principal. For example, AWS: arn:aws:iam::account-id:role/ecsInstanceRole. The role must exist in the secondary account before you save the repository policy. If it doesn't exist, then you receive an error similar to the following: invalid repository policy provided.

The following example repository policy allows a specific account to push and pull images:

  "Version": "2012-10-17",
  "Statement": [
      "Sid": "AllowPushPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::account-id:root"
      "Action": [

5.    In the task definition, set the image that you want to use with Amazon ECS. Your image is hosted in the primary account's Amazon ECR repository.
Note: Make sure that your secondary account has Amazon ECR permissions listed in "AmazonEC2ContainerRegistryPowerUser" managed policy. These permissions are required to pull or push from your primary account.

Generate a temporary Docker authentication token from the secondary account and perform a test push or pull

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

The secondary account can't perform policy actions on the repository until it receives a temporary authentication token that's valid for 12 hours. The token allows the secondary account to use Docker push and pull commands against the primary account's repository. The get-login-password command retrieves and decodes the authorization token that you can then pipe into a docker login command to authenticate.

Note: The account that gets the token must have the relevant AWS Identify and Access Management (IAM) API permissions to modify the repository. For examples, see AWS managed policies for Amazon Elastic Container Registry. To troubleshoot issues with Docker, turn on debug mode on your Docker daemon. This command is supported using the latest version of AWS CLI version 2, or in v1.17.10 or later of AWS CLI version 1. For more information, see get-login-password.

1.    To generate a Docker authentication token for an account that pushes and pulls images outside of Amazon ECS, run the following command. Replace aws_account_id with your primary account ID, and replace regionID with your Region ID.

Using the AWS CLI:

aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin

Using AWS Tools for Windows PowerShell:

(Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin

You receive the following output:

aws ecr get-login-password --region ap-south-1 | docker login --username AWS --password-stdin
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See
Login Succeeded

2.    Perform a test image pull from or push to the primary account:

docker pull

Note: Replace AccountID and Region with your account ID and Region. Replace ImageName and TagName with the name of your image and tag.

3.    Validate that the image downloaded successfully:

docker images | grep ImageName

Note: Replace ImageName with the name of your image.

AWS OFFICIALUpdated 2 years ago