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

Short description

To allow a secondary account to push or pull images from your Amazon ECR repository, create a registry or repository policy in your primary account. To provide access to all repositories in your AWS Region or to multiple different repositories, configure a registry-level policy. To provide access to only one repository or restrict access for different identities within a single repository, configure a repository-level policy. Configure the policy to allow specific API calls from the secondary account.

Then, from the secondary account, generate a Docker authentication token to push and pull images from the primary account's repository.

Resolution

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

Configure registry level permissions

Prerequisite: Your Amazon ECR registry must use a V2 policy. If you use a V1 policy, then switch to V2. For more information about the V2 policy, see Amazon ECR expands registry policy to all ECR actions.

Complete the following steps:

1. Open the Amazon ECR console for your primary account.
2. In the navigation pane, under Private registry, choose Features & Settings.
3. Choose Permissions.
4. Choose Edit JSON.
5. Enter your policy into the editor. Example policy that allows the secondary account to push and pull images across all repositories in the Region:

    {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::account-id:root"
         },
         "Action": [
           "ecr:GetDownloadUrlForLayer",
           "ecr:BatchGetImage",
           "ecr:BatchCheckLayerAvailability",
           "ecr:PutImage",
           "ecr:InitiateLayerUpload",
           "ecr:UploadLayerPart",
           "ecr:CompleteLayerUpload"
         ],
         "Resource": "*"
       }
     ]
   }

   Note: Replace account-id with the secondary account ID. For Action, enter the actions that the account can perform in the repository. To allow access to a specific role, provide the role Amazon Resource Name (ARN) for the Principal, such as AWS: arn:aws:iam::account-id:role/ecsInstanceRole. Before you save the registry policy, make sure that the role you entered exists in the secondary account. If the role doesn't exist, then you receive the "invalid registry policy provided" error.
6. Choose Save.

Configure repository level permissions

Complete the following steps:

1. Open the Amazon ECR console for your primary account.
2. In the navigation pane, under Private registry, choose Repositories.
3. Choose the repository that you want to modify.
4. In the navigation pane, choose Permissions.
5. Choose Edit policy JSON.
6. In the policy editor, enter your policy statement.
   Example repository policy that allows an account to push and pull images:

   {  "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowPushPull",
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::account-id:root"
         },
         "Action": [
           "ecr:GetDownloadUrlForLayer",
           "ecr:BatchGetImage",
           "ecr:BatchCheckLayerAvailability",
           "ecr:PutImage",
           "ecr:InitiateLayerUpload",
           "ecr:UploadLayerPart",
           "ecr:CompleteLayerUpload"
         ]
       }
     ]
   }

   Note: Replace account-id with the secondary account ID. For Action, enter the actions that the account can perform in the repository. To allow access to a specific role, provide the role Amazon Resource Name (ARN) for the Principal, such as AWS: arn:aws:iam::account-id:role/ecsInstanceRole. Before you save the registry policy, make sure that the role you entered exists in the secondary account. If the role doesn't exist, then you receive the "invalid registry policy provided" error.
7. Choose Save.
8. If you use Amazon ECS to run the container in the secondary account, then set the image that you want to use with Amazon ECS. The primary account's Amazon ECR repository hosts the image.

Note: Make sure that the AmazonEC2ContainerRegistryPowerUser managed policy includes the Amazon ECR permissions for your secondary account. You must have these permissions to pull or push from your primary account.

Generate a temporary Docker authentication token

Note: The account that gets the token must have the required AWS Identify and Access Management (IAM) API permissions to modify the repository. For examples, see AWS managed policies for Amazon ECR. To troubleshoot issues with Docker, turn on debug mode on your Docker daemon.

Complete the following steps:

1. To generate a Docker authentication token for an account that pushes and pulls images outside of Amazon ECS, run the following get-login-password AWS CLI command:

   aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin AWS_ACCOUNT_ID.dkr.ecr.REGION-ID.amazonaws.com

   -or-
   Run the following AWS Tools for Windows PowerShell command:

   (Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin AWS_ACCOUNT_ID.dkr.ecr.regionID.amazonaws.com

   Note: Replace AWS-ACCOUNT-ID with your primary account ID and REGION-ID with your Region. The temporary authentication token is valid for 12 hours.
   Example output:

   aws ecr get-login-password --region ap-south-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-south-1.amazonaws.com 
   WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
   Configure a credential helper to remove this warning. See https://docs.docker.com/engine/reference/commandline/login/#credentials-store
   Login Succeeded
   
   or 
   
   Login Succeeded

2. To perform a test image pull from or push to the primary account, run the following command:

   docker pull ACCOUNT-ID.dkr.ecr.REGION.amazonaws.com/REPOSITORY-NAME:TAG-NAME

   Note: Replace ACCOUNT-ID with your primary account ID, REGION with your Region, REPOSITORY-NAME with your repository name, and TAG-NAME with the tag name for your image.

3. To validate that you downloaded the image successfully, run the following command:

   docker images | grep IMAGE-NAME

   Note: Replace IMAGE-NAME with the name of your image.