Elastic Container Registry

Amazon Elastic Container Registry (ECR) is the AWS registry service for private and public container images. Use it as the registry in front of ECS, EKS, SageMaker, Batch, Lambda container images, and any other AWS service that pulls Docker-compatible images.

Set variables for the examples.

1export AWS_REGION=us-east-1
2export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
3export ECR_REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
4export ECR_REPOSITORY="student-rest"
5export IMAGE_TAG="$(git rev-parse --short HEAD)"

Create a private repository. Enable tag immutability for release repositories so pushed tags cannot be overwritten accidentally. Enable scan-on-push for immediate basic scanning, and use Amazon Inspector enhanced scanning when the account needs continuous vulnerability coverage.

1aws ecr create-repository \
2    --region "${AWS_REGION}" \
3    --repository-name "${ECR_REPOSITORY}" \
4    --image-tag-mutability IMMUTABLE \
5    --image-scanning-configuration scanOnPush=true

Authenticate Docker to ECR. The authorization token is temporary, so CI jobs should log in during each run.

1aws ecr get-login-password --region "${AWS_REGION}" \
2    | docker login --username AWS --password-stdin "${ECR_REGISTRY}"

Build and push

Build with Buildx and push directly to ECR.

1docker buildx build \
2    --platform linux/amd64 \
3    -t "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}" \
4    -t "${ECR_REGISTRY}/${ECR_REPOSITORY}:latest" \
5    --push .

For multi-platform images, publish a manifest list.

1docker buildx build \
2    --platform linux/amd64,linux/arm64 \
3    -t "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}" \
4    --push .

Inspect the pushed image.

1aws ecr describe-images \
2    --region "${AWS_REGION}" \
3    --repository-name "${ECR_REPOSITORY}" \
4    --image-ids imageTag="${IMAGE_TAG}"

Pull by digest

Tags are convenient for humans. Deployments should record the digest that was promoted.

 1IMAGE_DIGEST="$(
 2    aws ecr describe-images \
 3        --region "${AWS_REGION}" \
 4        --repository-name "${ECR_REPOSITORY}" \
 5        --image-ids imageTag="${IMAGE_TAG}" \
 6        --query 'imageDetails[0].imageDigest' \
 7        --output text
 8)"
 9
10echo "${ECR_REGISTRY}/${ECR_REPOSITORY}@${IMAGE_DIGEST}"

Repository controls

Use repository and registry controls deliberately.

  • Turn on immutable tags for release repositories.

  • Turn on scan-on-push, and use enhanced scanning for continuous monitoring.

  • Use lifecycle policies for feature-branch images and BuildKit cache tags.

  • Use separate AWS accounts or repositories for development, staging, and production.

  • Grant push permissions only to build roles and pull permissions only to deployment roles.

  • Prefer KMS encryption when the organization requires customer-managed keys.

References