Replication backfill

You can replicate preexisting images in your Amazon ECR private registry to your configured replication destinations. By default, replication only applies to images pushed after the replication configuration is applied. Replication backfill allows you to replicate images that you pushed before you configured replication.

How replication backfill works

When you start a replication backfill, you specify a single destination consisting of a Region and registry ID. Amazon ECR evaluates your existing replication configuration to determine which images in your registry qualify for backfill to the specified destination. Only images that match your current replication configuration rules are included in the backfill.

Each replication backfill targets a single destination. To backfill images to multiple destinations, start a separate replication backfill for each destination. Each one is identified by a unique replicationBackfillId that you use to monitor progress, view results, and stop it if needed.

Replication backfill lifecycle

A replication backfill transitions through the following statuses:

• PREPARING: Amazon ECR is identifying qualifying images in your registry.

• IN_PROGRESS: Amazon ECR is actively replicating images to the destination.

• COMPLETE: All qualifying images were successfully replicated.

• FAILED: A replication backfill automatically fails if 50% or more of the underlying replications fail. This threshold is only evaluated once at least 100 replications are processed.

• STOPPING: A stop was requested and Amazon ECR is waiting for in-flight replications to complete.

• STOPPED: You stopped the replication backfill and all in-flight replications have ended.

Note

You can stop a replication backfill only when it is in the PREPARING or IN_PROGRESS status.

Considerations for replication backfill

The following should be considered when using replication backfill.

• Only images that match your current replication configuration for the specified destination are included in the backfill. If you need to backfill images to a destination that is not in your replication configuration, you must first add that destination to your replication rules.

• You can run up to 10 replication backfills concurrently per registry. If you start more, Amazon ECR returns a LimitExceededException error.

• You can have only one active replication backfill for a given destination Region at a time. A second request for the same destination Region returns a ReplicationBackfillInProgressException error.

• Amazon ECR retains replication backfills in a terminal state (COMPLETE, FAILED, or STOPPED) for 90 days after completion. During that time, they remain visible in ListReplicationBackfills responses.

• Stopping a replication backfill does not roll back images that it already replicated. Those images remain in the destination registry.

• Replication backfill uses the same service-linked role that Amazon ECR creates when you first configure replication for your private registry.

• Most registries are expected to complete backfill within an hour. However, a registry that contains a large amount of data can take hours or even days to fully backfill.

• Replication backfill skips images whose source repository was deleted. Those images appear with a FAILED status in the backfill results.

• Amazon ECR sends an EventBridge event when a replication backfill reaches a terminal status. For more information, see Sample events from Amazon ECR.

Starting a replication backfill

To start a replication backfill (AWS Management Console)

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories.

2. From the navigation bar, choose the Region of the source registry to backfill from.

3. In the navigation pane, choose Private registry.

4. On the Private registry page, choose Settings and then choose Edit under Replication configuration.

5. On the Replication page, choose the Backfill jobs tab.

6. Choose Start backfill job.

7. Choose up to 10 destinations that you want to backfill to.

8. Choose Start backfill jobs.

To start a replication backfill (AWS CLI)

• Start a replication backfill.

  aws ecr start-replication-backfill \
      --region us-west-2 \
      --registry-id aws_account_id \
      --destination region=destination_region,registryId=destination_aws_account_id

Monitoring replication backfill progress and viewing results

To monitor replication backfill progress and view replication backfill results (AWS Management Console)

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories.

2. From the navigation bar, choose the Region that contains your replication backfills.

3. In the navigation pane, choose Private registry.

4. On the Private registry page, choose Settings and then choose Edit under Replication configuration.

5. On the Replication page, choose the Backfill jobs tab to monitor the progress and view the results of your replication backfills.

To monitor replication backfill progress and view replication backfill results (AWS CLI)

1. To monitor the progress or view the results of a replication backfill, run the following command. While the replication backfill is in progress, the response contains only progress counts. Per-image results and pagination are available only after it completes.

   aws ecr describe-replication-backfill-results \
       --region us-west-2 \
       --registry-id aws_account_id \
       --replication-backfill-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
       --max-results 1000 \
       --result-status-filter COMPLETE

2. To view summary information of all replication backfills, run the following command.

   aws ecr list-replication-backfills \
       --region us-west-2 \
       --registry-id aws_account_id \
       --max-results 50

Stopping a replication backfill

To stop a replication backfill (AWS Management Console)

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories.

2. From the navigation bar, choose the Region that contains your replication backfills.

3. In the navigation pane, choose Private registry.

4. On the Private registry page, choose Settings and then choose Edit under Replication configuration.

5. On the Replication page, choose the Backfill jobs tab.

6. Choose the replication backfill that you want to stop.

7. Choose Stop backfill job.

To stop a replication backfill (AWS CLI)

• To stop a replication backfill, run the following command.

  aws ecr stop-replication-backfill \
      --region us-west-2 \
      --registry-id aws_account_id \
      --replication-backfill-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111