Amazon ECR - Image Registry Replication


This exercise will show you the steps to enable record replication in the Amazon Elastic Container Registry. In a multi-region scenario, stored container images must be available in a secondary region before the application can be configured during the disaster.

By the end of this exercise, you will be able to:

  • Set Up Replication to Another Region of an Amazon ECR Image Record
  • List images and verify that replication is working according to the applied configuration.

Estimated Duration: 15 minutes

Approximate Cost: 1 USD


If you haven’t already created your environment on AWS Cloud9, start by creating your workspace. Click here.

For this exercise, use N. Virginia (us-east-1) like the main region and the N. California (us-west-1) like the secondary region.

Create a Repository in the Registry

  1. Save your AWS account ID to an environment variable.

    sudo yum install jq -y
    export AWSACCOUNT=$(aws sts get-caller-identity | jq -r '.Account')
  2. Create a repository in registry private. Note: Every AWS Account already has one registry private.

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

Create an image and push to the created Repository

  1. Create a test page: index.html

    cat > index.html << EOF
        <!doctype html>
        <html lang="en">
                <meta charset="utf-8">
                <title>Docker Nginx</title>
                <h2>Hello from Nginx container</h2>
  2. Create the Dockerfile

    cat > Dockerfile << EOF
    FROM nginx:latest
    COPY ./index.html /usr/share/nginx/html/index.html
  3. Execute the docker build in order to create the docker image with the repository name.

    docker build -t $ .
  4. To push the image to the repository using docker, you must authenticate to the repository first. To do this, use the get-login command and get the password to authenticate the docker with the docker login command.

    aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $
  5. After authenticating, upload your new image using the docker push command.

    docker push $
  6. (Optional) List the images in the Images Registry.

    aws ecr list-images --repository-name ecr-repository --region us-east-1

Set up replication for another region in the image registry

  1. Get the record id.

    export REGISTRYID=$(aws ecr describe-registry | jq -r '.registryId')
  2. Create a json file with configuration parameters. Replace the registration id for your environment. Notice that the replication configuration will replicate to the California (us-west-1).

    cat > replication.json << EOF
        "rules": [ 
                "destinations": [ 
                        "region": "us-west-1", 
                        "registryId": "$REGISTRYID" 
  3. Enable replication with the command below.

    aws ecr put-replication-configuration \
      --replication-configuration file://replication.json \
      --region us-east-1

Make an update to the image

  1. Update the container image by generating a new version with the following command.

    docker build -t $ .
  2. Push the new version. Notice that the push takes place to the region of origin, in this case N.Virginia (us-east-1).

    docker push $

Validate that the image is in both regions

  1. List the image repositories from both regions. On the return of the command, note the parameter RepositoryURI.

    aws ecr describe-repositories --region us-east-1
    aws ecr describe-repositories --region us-west-1
  2. List images from both regions. Note that the images are the same size, the same manifest. However, the push date in the repository is slightly different (ImagePushedAt parameter).

    aws ecr describe-images --repository-name ecr-repository --region us-east-1
    aws ecr describe-images --repository-name ecr-repository --region us-west-1

    Just image tags created after the activation of the replication it will be replicated to the secondary registry.

Cleaning up

  1. Delete images created in repositories

    aws ecr batch-delete-image \
      --repository-name ecr-repository \
      --image-ids imageTag=webapp imageTag=webapp2 \
      --region us-east-1
    aws ecr batch-delete-image \
      --repository-name ecr-repository \
      --image-ids imageTag=webapp imageTag=webapp2 \
      --region us-west-1
  2. Delete created repositories

    aws ecr delete-repository --repository-name ecr-repository --region us-east-1
    aws ecr delete-repository --repository-name ecr-repository --region us-west-1


With this exercise, it was possible to understand how to set up an Amazon Elastic Container Registry image repository, push an image to the repository, configure replication with a second region, update the image, and verify that image replication was successfully performed for the second region .

Source: Cross region replication in Amazon ECR has landed