Vijay T - Technical Blog

Logging in to Amazon Elastic Container Registry (ECR) with Docker

When working with Docker images stored in Amazon ECR, you need to authenticate Docker with the registry. Below is a concise, step‑by‑step guide to get you logged in quickly and securely.

---

1. Verify Your AWS Credentials

Make sure the AWS CLI is configured with an IAM user or role that has permission to access ECR.

aws configure list

You should see your access key, secret key, region, and output format. If anything is missing, run aws configure to set them up.

---

2. Retrieve an ECR Authentication Token

ECR uses short‑lived authentication tokens instead of static passwords. Pull a token for the desired region:

aws ecr get-login-password --region <your-region>

Replace <your-region> with the region where your repository lives (e.g., us-west-2).
The command outputs a long string – this is the token you’ll feed to Docker.

---

3. Log In to the Registry

Use the token from the previous step with Docker’s login command. The username is always AWS. Pipe the token into Docker to avoid exposing it on the command line.

aws ecr get-login-password --region <your-region> \
  | docker login -u AWS --password-stdin <account-id>.dkr.ecr.<your-region>.amazonaws.com

Parameters to replace

Placeholder	Description
<your-region>	AWS region of the ECR repository (e.g., us-east-1).
<account-id>	Your 12‑digit AWS account ID.

Example

aws ecr get-login-password --region us-west-2 \
  | docker login -u AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com

If the login succeeds, Docker will print:

Login Succeeded

---

4. (Optional) Use the Legacy aws ecr get-login Helper

Older AWS CLI versions provide a helper that returns a ready‑made docker login command:

aws ecr get-login --region <your-region> --registry-ids <account-id>

You can execute the output directly:

$(aws ecr get-login --region us-west-2 --registry-ids 123456789012)

Note: This approach embeds the password in the command line, which can be visible to other users on the same host. The --password-stdin method shown earlier is more secure.

---

5. Common Pitfalls & Tips

Issue	Likely Cause	Fix
Login Succeeded never appears	Incorrect region or account ID, or missing IAM permissions	Double‑check region, account ID, and IAM policies (ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, etc.).
aws: command not found	AWS CLI not installed or not in $PATH	Install the AWS CLI: curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" → unzip → sudo ./aws/install.
Token expires after a few hours	Using an old token	Tokens are valid for 12 hours; re‑run the aws ecr get-login-password command when needed.
Docker cannot resolve the registry URL	Typo in the URL or DNS issue	Verify the URL format: <account-id>.dkr.ecr.<region>.amazonaws.com.

---

6. Next Steps After Login

Once authenticated, you can push or pull images just like with any Docker registry:

# Tag a local image for ECR
docker tag my-app:latest <account-id>.dkr.ecr.<your-region>.amazonaws.com/my-repo:latest

# Push the image
docker push <account-id>.dkr.ecr.<your-region>.amazonaws.com/my-repo:latest

# Pull the image on another host (after logging in there as well)
docker pull <account-id>.dkr.ecr.<your-region>.amazonaws.com/my-repo:latest

---

TL;DR Command Summary

# 1️⃣ Get token & log in (recommended)
aws ecr get-login-password --region <your-region> \
  | docker login -u AWS --password-stdin <account-id>.dkr.ecr.<your-region>.amazonaws.com

# 2️⃣ (Legacy) One‑liner that prints a ready‑made login command
$(aws ecr get-login --region <your-region> --registry-ids <account-id>)

With these steps, Docker is reliably authenticated to your Amazon ECR repository, enabling smooth image workflows across your development, CI/CD, and production environments. Happy containerizing!