Home

Publishing Docker Images to ECR Private Registries

Colin J. Ihrig

Amazon's Elastic Container Registry (ECR) is a fully managed Docker container registry. If you have ever used Docker Hub, ECR is essentially the AWS equivalent. You can push to, pull from, and otherwise interact with ECR using the Docker CLI tools.

Some reasons for choosing ECR may be:

  • Your job requires it.
  • You already have everything else in AWS. In addition to having everything in one place, AWS can provide integrations between its own services that may not be available with third party container registries.
  • Potential price savings. See the pricing page to be sure.

Private registries

ECR provides a public container registry that the world can access. However, ECR also provides private registries for each AWS account. The naming convention for private ECR registries is:

aws_account_id.dkr.ecr.region_name.amazonaws.com

For example, if your AWS account ID is 123456789012, and you are working in the us-east-1 region, then your private ECR registry can be accessed at:

123456789012.dkr.ecr.us-east-1.amazonaws.com

When using the AWS CLI, commands that use a private registry start with aws ecr. This is different from commands that use the public registry, which start with aws ecr-public. Private registry example commands include:

aws ecr describe-registries
aws ecr get-login-password

Authenticating to an ECR registry

To authenticate with a registry you need a username and password. The username will be AWS. To obtain the password for a private registry, use the aws ecr get-login-password command.

Using the AWS account ID 123456789012 in the us-east-1 region, you can authenticate the Docker CLI with the following command:

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

If you are using Helm, it can be similarly authenticated with the following command:

aws ecr get-login-password --region us-east-1 | helm registry login \
  --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

Create a repository

Create a repository to hold your Docker images using the aws ecr create-repository command. The following command creates a repository named project-name in your private registry in the us-east-1 region:

aws ecr create-repository --repository-name project-name --region us-east-1

Tag and push an image

Run the docker images command to see the available images on your machine. Then, use the docker tag command to create a tag. Next, use the docker push command to upload the image to your private registry. The following commands would tag and upload an image with the local image ID 439c953b5bd7:

docker tag 439c953b5bd7 123456789012.dkr.ecr.us-east-1.amazonaws.com/project-name:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/project-name:latest

Finally, you can verify that the image was successfully uploaded using the docker pull command:

docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/project-name:latest

Alternatively, you can use the following AWS CLI commands to inspect your registry, repositories, and images:

aws ecr describe-registry --region us-east-1
aws ecr describe-repositories --region us-east-1
aws ecr describe-images --region us-east-1 --repository-name project-name

Cleaning up

If you need to clean up the resources you've created, you can use the aws ecr delete-repository command with the --force flag. The --force flag is used to delete a repository that contains images. You can also delete the images individually if you wish to avoid using the --force flag.