Cross-Account Amazon ECR Image Access from EC2: A Secure IAM-Based Approach

Introduction
In many real-world AWS environments, applications and workloads often run in one AWS account while container images are stored in another. This pattern is common in multi-account setups, enterprises, managed service providers, and vendor-hosted solutions.

A typical example:

• Account A (Consumer): Runs EC2 instances or applications
• Account B (Source): Hosts container images in Amazon ECR

The challenge:
EC2 instances in Account A cannot directly pull Docker images from ECR in Account B.

👉 To solve this, AWS supports secure cross-account ECR access using IAM Roles + ECR Repository Policies.

Architecture Overview

1. EC2 instance in Account A assumes an IAM Role
2. IAM Role has permission to authenticate with ECR
3. ECR Repository in Account B trusts this IAM role
4. EC2 logs in → pulls the container image

Step 1: Create IAM Role for EC2 in Account A

You need an IAM Role that your EC2 instance will use.

1.1 Choose EC2 as the trusted entity

During IAM role creation:

Trusted Entity: EC2
“Allows EC2 instances to call AWS services on your behalf”

1.2 Attach the policy below:
🔐 IAM Policy: Allow EC2 to Pull Images from Account B

(This goes into Account A, attached to the EC2 IAM Role)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GetAuthToken",
            "Effect": "Allow",
            "Action": "ecr:GetAuthorizationToken",
            "Resource": "*"
        },
        {
            "Sid": "PullImages",
            "Effect": "Allow",
            "Action": [
                "ecr:BatchGetImage",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchCheckLayerAvailability"
            ],
            "Resource": "arn:aws:ecr:us-east-1:<ACCOUNT_B_ID>:repository/<REPO_NAME>"
        }
    ]
}

Why "Resource": "*" on GetAuthorizationToken?

Because AWS does not support resource-level restrictions for this API.
This is required and safe.

Step 2: Attach the IAM Role to the EC2 instance

EC2 → Instance → Actions → Security → Modify IAM Role → Select your role

Your EC2 is now authorized to pull images — but ECR in Account B must still trust it.

🔐 ECR Repository Policy (Account B → Allows Account A to Pull)

This explicitly tells the ECR repo that the IAM role from Account A is allowed to pull images.

👉 We need to update the ECR repository permissions in Account B.

Step 4: Install Docker & AWS CLI on EC2

If you haven't installed Docker:

For Amazon Linux 3:

sudo yum update -y
sudo yum install -y docker
sudo service docker start
sudo usermod -aG docker ec2-user

Step 5: Authenticate Docker to the Account B ECR

aws ecr get-login-password --region us-east-1 \
| docker login --username AWS \
  --password-stdin <ACCOUNT_B_ID>.dkr.ecr.us-east-1.amazonaws.com

Step 6: Pull the Image

docker pull <ACCOUNT_B_ID>.dkr.ecr.us-east-1.amazonaws.com/<REPO_NAME>:latest

Troubleshooting Checklist
❌ Error: no basic auth credentials

1. docker login not executed
2. IAM role missing pull permissions
3. ECR repo does not trust Account A

❌ Error: access denied

ECR repo policy missing Account A IAM role

❌ Error: repository not found

1. wrong region
2. wrong repo name

❌ Error: docker not found

Best Practices

✔ Always use IAM Roles, never access keys
✔ Always restrict pull access using ECR repository policy
✔ Never use wildcard "" for image pull actions
✔ Use "" only for GetAuthorizationToken (required by AWS)
✔ Consider using Lifecycle Policies for cleaning old images
✔ Consider enabling ECR scan-on-push for security