# Private image replication in Amazon ECR
You can configure your Amazon ECR private registry to support the replication of your repositories. Amazon ECR supports both cross-Region and cross-account replication. For cross-account replication to occur, the destination account must configure a registry permissions policy to allow replication from the source registry to occur. For more information, see [Private registry permissions in Amazon ECR](registry-permissions.md).
**Topics**
+ [Cross-account replication policy requirements](#replication-policy-clarification)
+ [Considerations for private image replication](#replication-considerations)
+ [Private image replication examples for Amazon ECR](registry-settings-examples.md)
+ [Configuring private image replication in Amazon ECR](registry-settings-configure.md)
+ [Removing private image replication settings in Amazon ECR](registry-settings-remove.md)
## Cross-account replication policy requirements
For cross-account ECR replication to work properly, you must understand which account needs which policies configured. This section clarifies the policy requirements for both source and destination accounts.
### Policy configuration overview
Cross-account ECR replication requires policy configuration on the **destination account only**. The source account does not require any special repository or registry policies.
+ **Source Account**: Configure replication rules in the registry settings. No additional policies required on source repositories.
+ **Destination Account**: Configure a registry permissions policy to allow the source account to replicate images.
### Destination registry policy requirements
The destination account must configure a registry permissions policy that grants the source account permission to perform the following actions:
+ `ecr:ReplicateImage` - Allows the source account to replicate images to the destination registry
+ `ecr:CreateRepository` - Allows ECR to automatically create repositories in the destination registry if they don't already exist
**Important**
If you do not grant the `ecr:CreateRepository` permission, you must manually create repositories with the same names in the destination account before replication can succeed.
Example destination registry policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCrossAccountReplication",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": [
"ecr:ReplicateImage",
"ecr:CreateRepository"
],
"Resource": "*"
}
]
}
```
------
### Source account requirements
The source account only needs to:
+ Configure replication rules in the registry settings to specify the destination account and regions
+ Ensure the IAM principal configuring replication has the necessary ECR permissions
**No additional policies are required on source repositories.** The source repositories do not need repository policies that grant replication permissions.
### Common misconceptions
The following are common misconceptions about ECR cross-account replication policies:
+ **Misconception**: The source repository needs a policy allowing the destination account to replicate images.
**Reality**: Source repositories do not need any special policies for replication.
+ **Misconception**: Both source and destination accounts need registry policies.
**Reality**: Only the destination account needs a registry permissions policy.
+ **Misconception**: Repository policies and registry policies are the same thing.
**Reality**: Repository policies control access to individual repositories, while registry policies control registry-level operations like replication.
### Troubleshooting replication failures
If cross-account replication is failing, check the following:
+ Verify the destination account has a registry permissions policy configured
+ Ensure the registry policy includes both `ecr:ReplicateImage` and `ecr:CreateRepository` actions
+ Confirm the source account ID is correctly specified in the destination registry policy
+ Check that the destination repositories exist (if `ecr:CreateRepository` is not granted)
+ Review CloudTrail logs for failed `CreateRepository` or `ReplicateImage` API calls
## Considerations for private image replication
The following should be considered when using private image replication.
+ Only repository content pushed or restored to a repository after replication is configured is replicated. Any preexisting content in a repository isn't replicated. If an image is restored after replication is turned on, it will be replicated. If it is restored before replication is turned on, it won't be replicated.
+ 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](using-service-linked-roles.md).
+ 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 in Amazon ECR](registry-permissions.md).
+ 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 AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the *Amazon Web Services General Reference*.
+ Cross-Region replication is not supported between AWS partitions. For example, a repository in `us-west-2` can't be replicated to ` cn-north-1`. For more information about AWS partitions, see [ARN format](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) in the *AWS 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](registry-settings-examples.md#registry-settings-examples-crr-filter).
+ A replication action only occurs once per image push or image restore. 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 or archive actions. Replicated images and repositories can be deleted or archived when they are no longer being used.
+ If the image to be replicated is archived in the destination, then it will be restored in the destination.
+ When an image is archived in a source region, it will not be archived in a destination region specified by the replication configuration.
+ 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 by default, you can replicate the repository settings using repository creation templates. These settings include tag mutability, encryption, repository permissions, and lifecycle policies. For more information about repository creation templates, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md).
+ 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.
+ When replicating images, if blob mounting has been configured, ECR will check to ensure any layers from the source repository already exist in the destination registry. If any layers already exist in the destination registry, ECR will mount those layers.
**Note**
If the source registry is different from its destination registry, blob mounting will need to be enabled for both registries for ECR to mount replicated layers.
# Private image replication examples for Amazon ECR
The following examples show common use cases for private image replication. If you configure replication by using the AWS CLI, you can use the JSON examples as a starting point when you create your JSON file. If you configure replication by using the AWS Management Console, you will see similar JSON when you review your replication rule on the **Review and submit** page.
## Example: Configuring cross-Region replication to a single destination Region
The following shows an example for configuring cross-Region replication within a single registry. This example assumes that your account ID is ` 111122223333` and that you're specifying this replication configuration in a Region other than `us-west-2`.
```
{
"rules": [
{
"destinations": [
{
"region": "us-west-2",
"registryId": "111122223333"
}
]
}
]
}
```
## Example: Configuring cross-Region replication using a repository filter
The following shows an example for configuring cross-Region replication for repositories that match a prefix name value. This example assumes your account ID is ` 111122223333` and that you're specifying this replication configuration in a Region other than `us-west-1` and have repositories with a prefix of `prod`.
```
{
"rules": [{
"destinations": [{
"region": "us-west-1",
"registryId": "111122223333"
}],
"repositoryFilters": [{
"filter": "prod",
"filterType": "PREFIX_MATCH"
}]
}]
}
```
## Example: Configuring cross-Region replication to multiple destination Regions
The following shows an example for configuring cross-Region replication within a single registry. This example assumes your account ID is ` 111122223333` and that you're specifying this replication configuration in a Region other than `us-west-1` or `us-west-2` .
```
{
"rules": [
{
"destinations": [
{
"region": "us-west-1",
"registryId": "111122223333"
},
{
"region": "us-west-2",
"registryId": "111122223333"
}
]
}
]
}
```
## Example: Configuring cross-account replication
The following shows an example for configuring cross-account replication for your registry. This example configures replication to the `444455556666` account and to the `us-west-2` Region.
**Important**
For cross-account replication to occur, the destination account must configure a registry permissions policy to allow replication to occur. For more information, see [Private registry permissions in Amazon ECR](registry-permissions.md).
```
{
"rules": [
{
"destinations": [
{
"region": "us-west-2",
"registryId": "444455556666"
}
]
}
]
}
```
## Example: Specifying multiple rules in a configuration
The following shows an example for configuring multiple replication rules for your registry. This example configures replication for the * 111122223333* account with one rule that replicates repositories with a prefix of `prod` to the `us-west-2` Region and repositories with a prefix of `test` to the `us-east-2` Region. A replication configuration may contain up to 10 rules, with each rule specifying up to 25 destinations.
```
{
"rules": [{
"destinations": [{
"region": "us-west-2",
"registryId": "111122223333"
}],
"repositoryFilters": [{
"filter": "prod",
"filterType": "PREFIX_MATCH"
}]
},
{
"destinations": [{
"region": "us-east-2",
"registryId": "111122223333"
}],
"repositoryFilters": [{
"filter": "test",
"filterType": "PREFIX_MATCH"
}]
}
]
}
```
## Example: Removing all replication settings
The following shows an example for removing all replication settings from your registry. To remove replication settings, you must configure an empty rules array.
```
{
"rules": []
}
```
**Important**
Removing replication settings does not delete any previously replicated repositories or images. You must manually delete replicated content if it is no longer needed.
# Configuring private image replication in Amazon ECR
Configure replication per Region for your private registry. You can configure cross-Region replication or cross-account replication.
For examples of how replication is commonly used, see [Private image replication examples for Amazon ECR](registry-settings-examples.md).
## To configure registry replication settings (AWS Management Console)
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region to configure your registry replication settings for.
1. In the navigation pane, choose **Private registry**.
1. On the **Private registry** page, choose ** Settings** and then choose **Edit** under **Replication configuration**.
1. On the **Replication** page, choose **Add replication rule**.
1. On the **Destination types** page, choose whether to enable cross-Region replication, cross-account replication, or both and then choose **Next**.
1. If cross-Region replication is enabled, then for **Configure destination regions**, choose one or more **Destination regions** and then choose **Next**.
1. If cross-account replication is enabled, then for **Cross-account replication**, choose the cross-account replication setting for the registry. For **Destination account**, enter the account ID for the destination account and one or more **Destination regions** to replicate to. Choose **Destination account \$1** to configure additional accounts as replication destinations.
**Important**
For cross-account replication to occur, the destination account must configure a registry permissions policy to allow replication to occur. For more information, see [Private registry permissions in Amazon ECR](registry-permissions.md).
1. (Optional) On the **Add filters** page, specify one or more filters for the replication rule and then choose **Add**. Repeat this step for each filter you want to associate with the replication action. A filter must be specified as a repository name prefix. If no filters are added, the contents of all repositories are replicated. Choose **Next** once all filters have been added.
1. On the **Review and submit** page, review the replication rule configuration and then choose **Submit rule**.
## To configure registry replication settings (AWS CLI)
1. Create a JSON file containing the replication rules to define for your registry. A replication configuration may contain up to 10 rules, with up to 25 unique destinations across all rules and 100 filters per each rule. To configure cross-Region replication within your own account, you specify your own account ID. For more examples, see [Private image replication examples for Amazon ECR](registry-settings-examples.md).
```
{
"rules": [{
"destinations": [{
"region": "destination_region",
"registryId": "destination_accountId"
}],
"repositoryFilters": [{
"filter": "repository_prefix_name",
"filterType": "PREFIX_MATCH"
}]
}]
}
```
1. Create a replication configuration for your registry.
```
aws ecr put-replication-configuration \
--replication-configuration file://replication-settings.json \
--region us-west-2
```
1. Confirm your registry settings.
```
aws ecr describe-registry \
--region us-west-2
```
# Removing private image replication settings in Amazon ECR
To remove or disable replication settings for your private registry, you need to configure an empty replication configuration. There is no dedicated removal command in the AWS CLI.
## To remove registry replication settings (AWS Management Console)
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region to remove your registry replication settings from.
1. In the navigation pane, choose **Private registry**.
1. On the **Private registry** page, choose ** Settings** and then choose **Edit** under **Replication configuration**.
1. Remove all existing replication rules by choosing the delete option for each rule.
1. Choose **Save** to apply the empty replication configuration.
## To remove registry replication settings (AWS CLI)
1. Create a JSON file with an empty rules array to remove all replication settings.
```
{
"rules": []
}
```
1. Apply the empty replication configuration to your registry.
```
aws ecr put-replication-configuration \
--replication-configuration file://empty-replication-settings.json \
--region us-west-2
```
1. Confirm that replication settings have been removed.
```
aws ecr describe-registry \
--region us-west-2
```
The output should show an empty `replicationConfiguration` with no rules.
**Important**
Removing replication settings does not delete any previously replicated repositories or images. You must manually delete replicated content if it is no longer needed.