Private image replication

Only repository content pushed to a repository after replication is configured is replicated. Any preexisting content in a repository isn't replicated. Once replication is configured for a repository, Amazon ECR keeps the destination and source synchronized.

The repository name will remain the same across Regions and accounts when replication has occurred. Amazon ECR doesn't support changing the repository name during replication.

The first time you configure your private registry for replication, Amazon ECR creates a service-linked IAM role on your behalf. The service-linked IAM role grants the Amazon ECR replication service the permission it needs to create repositories and replicate images in your registry. For more information, see Using service-linked roles for Amazon ECR.

For cross-account replication to occur, the private registry destination must grant permission to allow the source registry to replicate its images. This is done by setting a private registry permissions policy. For more information, see Private registry permissions.

If the permission policy for a private registry are changed to remove a permission, any in-progress replications previously granted may complete.

For cross-Region replication to occur, both the source and destination accounts must be opted-in to the Region prior to any replication actions occurring within or to that Region. For more information, see Managing Amazon Regions in the Amazon Web Services General Reference.

Cross-Region replication is not supported between Amazon partitions. For example, a repository in us-west-2 can't be replicated to cn-north-1. For more information about Amazon partitions, see ARN format in the Amazon General Reference.

The replication configuration for a private registry may contain up to 25 unique destinations across all rules, with a maximum of 10 rules total. Each rule may contain up to 100 filters. This allows for specifying separate rules for repositories containing images used for production and testing, for example.

The replication configuration supports filtering which repositories in a private registry are replicated by specifying a repository prefix. For an example, see Example: Configuring cross-Region replication using a repository filter.

A replication action only occurs once per image push. For example, if you configured cross-Region replication from us-west-2 to us-east-1 and from us-east-1 to us-east-2, an image pushed to us-west-2 replicates to only us-east-1, it doesn't replicate again to us-east-2. This behavior applies to both cross-Region and cross-account replication.

The majority of images replicate in less than 30 minutes, but in rare cases the replication might take longer.

Registry replication doesn't perform any delete actions. Replicated images and repositories can be manually deleted when they are no longer being used.

Repository policies, including IAM policies, and lifecycle policies aren't replicated and don't have any effect other than on the repository they are defined for.

Repository settings aren't replicated. The tag immutability, image scanning, and KMS encryption settings are disabled by default on all repositories created because of a replication action. The tag immutability and image scanning setting can be changed after the repository is created. However, the setting only applies to images pushed after the setting has changed.

If tag immutability is enabled on a repository and an image is replicated that uses the same tag as an existing image, the image is replicated but won't contain the duplicated tag. This might result in the image being untagged.