View a markdown version of this page

Replicating image deletions in Amazon ECR - Amazon ECR

Replicating image deletions in Amazon ECR

By default, Amazon ECR replication copies images to your replication destinations but does not replicate deletions. You can enable replication of deletes on a replication rule. When you enable replication of deletes, Amazon ECR replicates image deletions and image tag removals from the source registry to the replication destinations for that rule. This keeps your destination repositories consistent with the source without requiring you to delete images in each Region or account separately.

How replication of deletes works

Replication of deletes applies to the same repositories and destinations as the replication rule that you enable it on. When you enable replication of deletes, Amazon ECR replicates the following actions from the source registry to each replication destination.

  • When you remove a tag from an image that has other tags, Amazon ECR removes the same tag from the image in each destination repository.

  • When you remove the last tag from an image, Amazon ECR deletes the untagged image. Amazon ECR also deletes the corresponding digest and all related tags in each destination repository.

  • When you delete an image by digest, Amazon ECR deletes the image and all of its tags in each destination repository.

  • When a lifecycle policy expires an image in the source registry, Amazon ECR replicates the deletion to each destination repository.

Enabling replication of deletes

Amazon ECR doesn't replicate image deletions or image tag removals by default. You enable replication of deletes per replication rule by setting the deleteReplication parameter on the rule. If you don't set this parameter, Amazon ECR doesn't replicate image deletions or image tag removals for the replication rule. Amazon ECR replicates only the image deletions and image tag removals that occur after you enable replication of deletes. Amazon ECR doesn't replicate deletions that occurred before you enabled it.

To enable replication of deletes with the AWS CLI, update your replication configuration with the deleteReplication parameter set on the rule. For more information, see Configuring private image replication in Amazon ECR. In the following example, replace us-west-2 with your destination Region and replace the registry ID with your destination AWS account ID.

{ "rules": [ { "destinations": [ { "region": "us-west-2", "registryId": "111122223333" } ], "deleteReplication": { "enabled": true } } ] }

Ordering and consistency

Replication is asynchronous and eventually consistent. Image pushes and replicated deletions can arrive at a destination in a different order than they occurred in the source registry. Amazon ECR applies a replicated deletion only when the destination content still matches the source action. If the image or tag doesn't exist in the destination repository, or was changed by a more recent action, the replicated deletion has no effect. A replicated deletion occurs once. For example, if you configured replication from us-west-2 to us-east-1 and from us-east-1 to us-east-2, a deletion in us-west-2 is replicated only to us-east-1; it isn't replicated again to us-east-2.

Required permissions for replication of deletes

Amazon ECR uses the AWSServiceRoleForECRReplication service-linked role to replicate on your behalf. The role's ECRReplicationServiceRolePolicy policy includes the permissions Amazon ECR needs to replicate image deletions and image tag removals. For more information, see Using service-linked roles for Amazon ECR.

For cross-account replication, the destination registry must grant the source account the ecr:ReplicateImageDelete permission in its registry permissions policy, in addition to the ecr:ReplicateImage and ecr:CreateRepository permissions. For more information, see Private registry permissions in Amazon ECR.

Monitoring replication of deletes

Amazon ECR emits an Amazon EventBridge event with the detail type ECR Replication Action and an action-type of REPLICATE_DELETE in the destination Region when a replicated deletion completes. For more information, see Amazon ECR events and EventBridge.

Replicated deletions are recorded in the destination account's CloudTrail logs as ReplicateImageDelete events. For more information, see Logging Amazon ECR actions with AWS CloudTrail.

Considerations for replication of deletes

  • Amazon ECR does not replicate repository deletions.

  • Amazon ECR replicates deletions only at the image level. Deleting a repository in the source Region doesn't delete the corresponding images in the destination repositories.

  • Amazon ECR replicates only the deletions that occur after you enable replication of deletes. There is no retroactive replication.