AWS AmazonECR medium security documentation change

Service: AmazonECR · 2025-09-10 · Security-related medium

File: AmazonECR/latest/userguide/replication.md

Summary

Added detailed documentation about cross-account replication policy requirements, clarifying source/destination account configurations and common misconceptions

Security assessment

The change explicitly documents required IAM permissions for secure cross-account replication, specifically addressing potential misconfigurations that could lead to unauthorized access. The addition of ecr:ReplicateImage and ecr:CreateRepository requirements directly relates to access control security.

Diff

diff --git a/AmazonECR/latest/userguide/replication.md b/AmazonECR/latest/userguide/replication.md
index 7c9081601..a8bd793e1 100644
--- a//AmazonECR/latest/userguide/replication.md
+++ b//AmazonECR/latest/userguide/replication.md
@@ -5 +5 @@
-Considerations for private image replication
+Replication policy requirementsConsiderations for private image replication
@@ -12,0 +13,2 @@ You can configure your Amazon ECR private registry to support the replication of
+  * Cross-account replication policy requirements
+
@@ -18,0 +21,101 @@ You can configure your Amazon ECR private registry to support the replication of
+  * [Removing private image replication settings in Amazon ECR](./registry-settings-remove.html)
+
+
+
+
+## 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:
+    
+    
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "AllowCrossAccountReplication",
+                "Effect": "Allow",
+                "Principal": {
+                    "AWS": "arn:aws:iam::SOURCE-ACCOUNT-ID:root"
+                },
+                "Action": [
+                    "ecr:ReplicateImage",
+                    "ecr:CreateRepository"
+                ]
+            }
+        ]
+    }
+
+### 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
+