AWS AmazonECR documentation change
Summary
Updated documentation for configuring image tag mutability in ECR repositories, including UI navigation changes, added exclusion filters for mutable/immutable tags, and expanded CLI/PowerShell command examples with exclusion filter parameters.
Security assessment
The changes clarify and expand documentation for tag immutability settings (a security feature that prevents unintended image modifications). The addition of exclusion filters allows granular control over tag mutability rules, which improves security posture by enabling exceptions where needed. However, there is no evidence this addresses a specific disclosed vulnerability or incident.
Diff
diff --git a/AmazonECR/latest/userguide/image-tag-mutability.md b/AmazonECR/latest/userguide/image-tag-mutability.md index fa8fc480e..ad1f5499d 100644 --- a//AmazonECR/latest/userguide/image-tag-mutability.md +++ b//AmazonECR/latest/userguide/image-tag-mutability.md @@ -21 +21 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 3. In the navigation pane, choose **Repositories**. + 3. In the navigation pane, choose **Repositories** under **Private registry**. @@ -23 +23 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 4. On the **Repositories** page, choose the **Private** tab and then select the repository to edit and choose **Edit**. +If you don't see **Repositories** , choose **Private registry** to expand the menu and then choose **Repositories**. @@ -25 +25 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 5. For **Tag immutability** , choose the tag mutability setting for the repository. Repositories configured with immutable tags prevent image tags from being overwritten. For more information, see [Preventing image tags from being overwritten in Amazon ECR](./image-tag-mutability.html). + 4. On the **Private repositories** page, choose the radio button before the repository name for which you want to set the image tag mutability settings. @@ -27 +27 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 6. For **Image scan settings** , while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan configuration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic scanning as well as define filters to specify which repositories are scanned. For more information, see [Scan images for software vulnerabilities in Amazon ECR](./image-scanning.html). + 5. Choose **Actions** and then choose **Repository** under **Edit**. @@ -29 +29 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 7. For **Encryption settings** , this is a view only field as the encryption settings for a repository can't be changed once the repository is created. + 6. For **Image tag immutability** , choose one of the following tag mutability settings for the repository. @@ -31 +31,9 @@ You can use the AWS Management Console and AWS CLI tools to set image tag mutabi - 8. Choose **Save** to update the repository settings. + * **Mutable** – Choose this option if you want image tags to be overwritten. Recommended for repositories using pull through cache actions to ensure Amazon ECR can update cached images. Additionally, to disable tag updates for a few mutable tags, enter tag names or use wildcards (*) to match multiple similar tags in the **Mutable tag exclusion** text box. + + * **Immutable** – Choose this option if you want to prevent image tags from being overwritten, and it applies to all tags and exclusions in the repository when pushing an image with existing tag. Amazon ECR returns an `ImageTagAlreadyExistsException` if you attempt to push an image with an existing tag. Additionally, to enable tag updates for a few immutable tags, enter tag names or use wildcards (*) to match multiple similar tags in the **Immutable tag exclusion** text box. + + 7. For **Image scan settings** , while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan configuration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic scanning as well as define filters to specify which repositories are scanned. For more information, see [Scan images for software vulnerabilities in Amazon ECR](./image-scanning.html). + + 8. For **Encryption settings** , this is a view only field as the encryption settings for a repository can't be changed once the repository is created. + + 9. Choose **Save** to update the repository settings. @@ -42 +50 @@ Use one of the following commands to create a new image repository with immutabl - * [create-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) (AWS CLI) + * [create-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) (AWS CLI) with image tag mutability @@ -46 +54,5 @@ Use one of the following commands to create a new image repository with immutabl - * [New-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) (AWS Tools for Windows PowerShell) + * [create-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) (AWS CLI) with image tag mutability exclusion filters + + aws ecr create-repository --repository-name name --image-tag-mutability IMMUTABLE_WITH_EXCLUSION --image-tag-mutability-exclusion-filters filterType=WILDCARD,filter=filter-text --region us-east-2 + + * [New-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) (AWS Tools for Windows PowerShell) with image tag mutability @@ -52,0 +65,7 @@ Use one of the following commands to create a new image repository with immutabl + * [New-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) (AWS Tools for Windows PowerShell) with image tag mutability exclusion filters + + New-ECRRepository -RepositoryName name -ImageTagMutability IMMUTABLE_WITH_EXCLUSION -ImageTagMutabilityExclusionFilter @{FilterType=WILDCARD Filter=filter-text} -Region us-east-2 -Force + + + + @@ -57 +76 @@ Use one of the following commands to update the image tag mutability settings fo - * [put-image-tag-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) (AWS CLI) + * [put-image-tag-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) (AWS CLI) with image tag mutability @@ -61 +80,5 @@ Use one of the following commands to update the image tag mutability settings fo - * [Write-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) (AWS Tools for Windows PowerShell) + * [put-image-tag-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) (AWS CLI) with image tag mutability exclusion filters + + aws ecr put-image-tag-mutability --repository-name name --image-tag-mutability IMMUTABLE_WITH_EXCLUSION --image-tag-mutability-exclusion-filters filterType=WILDCARD,filter=latest --region us-east-2 + + * [Write-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) (AWS Tools for Windows PowerShell) with image tag mutability @@ -64,0 +88,4 @@ Use one of the following commands to update the image tag mutability settings fo + * [Write-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) (AWS Tools for Windows PowerShell) with image tag mutability exclusion filters + + Write-ECRImageTagMutability -RepositoryName name -ImageTagMutability IMMUTABLE_WITH_EXCLUSION -ImageTagMutabilityExclusionFilter @{FilterType=WILDCARD Filter=latest} +