AWS Security ChangesHomeSearch

AWS AmazonECR: ECR encryption at rest: KMS grant retirement guidance updated

Service: AmazonECR · 2026-11-17 · Documentation medium

File: AmazonECR/latest/userguide/encryption-at-rest.md · Type: encryption

Summary

Clarifies AWS KMS grant handling for Amazon ECR repositories: adds guidance not to retire or revoke grants for deleted repositories when blob mounting is used, notes that unretired grants count toward the per-key KMS grant quota (request an increase instead of retiring ECR grants), updates the RetireGrant step description, and removes the 'Troubleshooting' section that instructed users to manually run `aws kms retire-grant` on ECR-created grants. Also includes heading/formatting normalization (`###### Important`/`###### Note` changed to plain text).

Security assessment

The change documents how ECR interacts with customer managed AWS KMS keys and grants, warning that manually retiring/revoking ECR-created grants breaks access to encrypted image layers (encryption-at-rest key access control) and that grants count against the KMS grant quota. It also removes prior instructions to manually retire grants, reducing the risk of users unintentionally destroying the access path needed to decrypt stored images. No specific vulnerability, CVE, or incident is referenced, so it is hardening guidance rather than a fix.

Evidence

  * The grants that Amazon ECR creates on your behalf should not be revoked. If you revoke the grant that gives Amazon ECR permission to use the AWS KMS keys in your account, Amazon ECR cannot access this data, encrypt new images pushed to the repository, or decrypt them when they are pulled. When you revoke a grant for Amazon ECR, the change occurs immediately. To revoke access rights, you should delete the repository rather than revoking the grant. When a repository is deleted, Amazon ECR retires the grants on your behalf. Don't retire or revoke the grants of a deleted repository yourself. Other repositories that reference image layers from the deleted repository through blob mounting need these grants to pull those layers.

Diff

diff --git a/AmazonECR/latest/userguide/encryption-at-rest.md b/AmazonECR/latest/userguide/encryption-at-rest.md
index ad5a0db..7d9404d 100644
--- a//AmazonECR/latest/userguide/encryption-at-rest.md
+++ b//AmazonECR/latest/userguide/encryption-at-rest.md
@@ -7 +7 @@
-ConsiderationsRequired IAM permissionsMonitoring Amazon ECR interaction with AWS KMSTroubleshooting
+ConsiderationsRequired IAM permissionsMonitoring Amazon ECR interaction with AWS KMS
@@ -11 +11 @@ ConsiderationsRequired IAM permissionsMonitoring Amazon ECR interaction with AWS
-###### Important
+Important
@@ -41 +41 @@ The following provides a high-level understanding of how Amazon ECR is integrate
-  8. When a repository is deleted, Amazon ECR sends two [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) requests to AWS KMS to retire the grants created for the repository.
+  8. When a repository is deleted, Amazon ECR sends two [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) requests to AWS KMS to retire the grants that it created for the repository. If your registry uses or has used blob mounting, Amazon ECR sends these requests only after no other repository references image layers from the deleted repository. For more information about blob mounting, see [Blob mounting in Amazon ECR](./blob-mounting.html).
@@ -56 +56,3 @@ The following points should be considered when using AWS KMS based encryption (S
-  * The grants that Amazon ECR creates on your behalf should not be revoked. If you revoke the grant that gives Amazon ECR permission to use the AWS KMS keys in your account, Amazon ECR cannot access this data, encrypt new images pushed to the repository, or decrypt them when they are pulled. When you revoke a grant for Amazon ECR, the change occurs immediately. To revoke access rights, you should delete the repository rather than revoking the grant. When a repository is deleted, Amazon ECR retires the grants on your behalf.
+  * The grants that Amazon ECR creates on your behalf should not be revoked. If you revoke the grant that gives Amazon ECR permission to use the AWS KMS keys in your account, Amazon ECR cannot access this data, encrypt new images pushed to the repository, or decrypt them when they are pulled. When you revoke a grant for Amazon ECR, the change occurs immediately. To revoke access rights, you should delete the repository rather than revoking the grant. When a repository is deleted, Amazon ECR retires the grants on your behalf. Don't retire or revoke the grants of a deleted repository yourself. Other repositories that reference image layers from the deleted repository through blob mounting need these grants to pull those layers.
+
+  * Grants that Amazon ECR hasn't retired count toward the AWS KMS quota on grants for each customer managed key, including grants for deleted repositories. If you reach this quota, request a quota increase. Don't retire Amazon ECR grants to free up quota. For more information about this quota and how to request an increase, see [Quotas](https://docs.aws.amazon.com/kms/latest/developerguide/limits.html) in the _AWS Key Management Service Developer Guide_.
@@ -132 +134 @@ The IAM user, IAM role, or AWS account creating your repositories must have the
-###### Note
+Note
@@ -227,29 +228,0 @@ For example, if the ARN of the repository is `arn:aws:ecr:`us-west-2`:`111122223
-## Troubleshooting
-
-When deleting an Amazon ECR repository with the console, if the repository is successfully deleted but Amazon ECR is unable to retire the grants added to your KMS key for your repository, you will receive the following error.
-    
-    
-    The repository [{repository-name}] has been deleted successfully but the grants created by the kmsKey [{kms_key}] failed to be retired
-
-When this occurs, you can retire the AWS KMS grants for the repository yourself.
-
-###### To retire AWS KMS grants for a repository manually
-
-  1. List the grants for the AWS KMS key used for the repository. The `key-id` value is included in the error you receive from the console. You can also use the `list-keys` command to list both the AWS managed keys and customer managed KMS keys in a specific Region in your account.
-    
-        aws kms list-grants \
-         --key-id b8d9ae76-080c-4043-9237-c815bfc21dfc 
-         --region us-west-2
-
-The output include an `EncryptionContextSubset` with the Amazon Resource Name (ARN) of your repository. This can be used to determine which grant added to the key is the one you want to retire. The `GrantId` value will be used when retiring the grant in the next step.
-
-  2. Retire each grant for the AWS KMS key added for the repository. Replace the value for `GrantId` with the ID of the grant from the output of the previous step.
-    
-        aws kms retire-grant \
-         --key-id b8d9ae76-080c-4043-9237-c815bfc21dfc \
-         --grant-id GrantId \
-         --region us-west-2
-
-
-
-