AWS ECR

AWS Elastic Container Registry (ECR)

AWS ECR is a managed service used to handle the lifecycle of Docker images. It is currently one of the more popular options for managing private container registries for internal use.

Since ECR is well-documented, the official documentation will often be referenced for setup.

Creating a Registry

Tips

• Most organizations will tyipcally have ECR set up with one registry. Unless you have a specific purpose for namespacing your registries, I recommend creating one registry for your account.

• The process of creating the Docker registry with ECR can be done with the AWS console and is rather simple. I suggest going through the process to create it with a UI as familiarity with the AWS console will help understand the available options.

Instructions

The ECR documentation covers some details regarding creating a Docker registry. It covers some details regarding authentication that will be covered below.

Run the following to authenticate against ECR. The token is valid for 12 hours. Without running this, docker pull and docker push won't work.

aws ecr get-login-password --region region | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com

If you receive a permissions error when you push or pull, it's likely that your token has expired. Since this command is a bit complex and used frequently, I find it very helpful to set up an alias for the command so that I don't need to keep referencing it.

Creating a Repository

Tips

• It's recommended to create one unique repository for the lifecycle of one Docker image. You should not create one Docker repository to manage Docker images from different applications.

• Tag immutability enabled is best practice and thus highly encouraged.

• KMS encryption is typically not needed unless requested by your security team.

Instructions

Follow the official instructions to create an ECR repository.

Pushing to a Repository

Tips

• While not required, it's idiomatic to use semantic versioning to name the versions of your images.

• You will need to run the aws ecr command to log in every 12 hours or your push will fail.

• If you selected the tag immutability option when creating the repository (which I recommend), you can't overwrite an existing image. You will need to increment the version.

Instructions

Tag your local Docker image with the appropriate ECR tag so Docker knows where it should push to.

docker tag <IMAGE_ID> aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag

Push the Docker image

docker push aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag

If you ever forget the exact steps to push a Docker image, the AWS Console conveniently has the steps detailed in every repository.

The instructions from the official documentation can be referenced here.

Pulling from a Repository

Tips

• You will need to run the aws ecr command to log in every 12 hours or your pull will fail.

Instructions

docker pull aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag