AWS imagebuilder documentation change
Summary
Major restructuring and expansion of AMI lifecycle rules documentation. Added sections on rule priority/evaluation order, tag usage distinctions, retention calculation, resource state transitions, and exclusion rule details. Clarified behavior differences between AMI/container images and improved operational guidance.
Security assessment
The changes document existing lifecycle management features without addressing any specific vulnerability. While disabling AMIs and deleting resources could indirectly improve security hygiene, there's no evidence of a security incident being fixed. Changes focus on operational clarity and cost optimization rather than security vulnerabilities.
Diff
diff --git a/imagebuilder/latest/userguide/image-lifecycle-rules.md b/imagebuilder/latest/userguide/image-lifecycle-rules.md index bfa23daf4..f49945d7d 100644 --- a//imagebuilder/latest/userguide/image-lifecycle-rules.md +++ b//imagebuilder/latest/userguide/image-lifecycle-rules.md @@ -7 +7 @@ -AMI lifecycle exclusion rulesView lifecycle management rule details +Rule priority and evaluation orderAMI lifecycle exclusion rulesTags as resource selectors vs. exclusion rulesHow retention is calculatedHow lifecycle actions affect associated resourcesAllowed resource state transitionsView lifecycle management rule details @@ -11 +11 @@ AMI lifecycle exclusion rulesView lifecycle management rule details -Image lifecycle policies use the lifecycle rules that you define to implement your overall resource management strategy. The rules that you define help ensure the freshness of your available images and minimize costs for underlying infrastructure such as snapshot storage for output AMIs, or ECR repository storage and data transfer rates for container images. +Lifecycle rules keep your images fresh and reduce infrastructure costs, such as snapshot storage for output AMIs and Amazon ECR repository storage for containers. @@ -13 +13 @@ Image lifecycle policies use the lifecycle rules that you define to implement yo -You can configure the following types of rules for your policies. +Lifecycle policies support these rule types: @@ -20 +20 @@ Sets the Image Builder image resource status to `Deprecated`. Image Builder pipe -When an AMI is deprecated, it's ignored by general searches. For example, if you run the Amazon EC2 **describe-images** command in the AWS CLI, it would not return deprecated AMIs in the result set. However, you can still find deprecated AMIs with their AMI ID. +Deprecated AMIs do not appear in general searches. For example, the Amazon EC2 **describe-images** command excludes deprecated AMIs from results. To find a deprecated AMI, specify its AMI ID directly. @@ -22 +22,3 @@ When an AMI is deprecated, it's ignored by general searches. For example, if you -_This rule is not available for container images._ +###### Note + +This rule does not apply to container-based images. @@ -29 +31,3 @@ Sets the Image Builder image resource status to `Disabled`. This prevents Image -When an AMI is disabled, it becomes private and can't be used to launch new instances. If you shared the AMI with any accounts, organizations, or organizational units, they lose access to your AMI when it becomes private. +A disabled AMI becomes private and no longer launches new instances. Accounts, organizations, or organizational units that previously had shared access lose that access. + +###### Note @@ -31 +35 @@ When an AMI is disabled, it becomes private and can't be used to launch new inst -_This rule is not available for container images._ +This rule does not apply to container-based images. @@ -38 +42,33 @@ Deletes the image resources by age or by count. You define the threshold that me -For container images, this rule deletes the Image Builder container image resource. You can optionally remove container images that were distributed to ECR repositories to prevent them from being used to run new containers. +For container images, this rule deletes the Image Builder container image resource. You can also remove container images from ECR repositories to prevent new container launches. + +## Rule priority and evaluation order + +When a policy has multiple rule types, Image Builder evaluates each resource in this order: + + 1. Deprecate rule + + 2. Disable rule + + 3. Delete rule + + + + +###### Important + +Only one action applies to each resource per execution. If a resource matches a deprecate rule, Image Builder deprecates it and skips the disable and delete rules for that resource during the same run. In subsequent executions, Image Builder evaluates the resource against other rules if it meets their criteria. + +This priority order supports a progressive lifecycle strategy. For example, you can configure a policy to deprecate images after 90 days, disable them after 120 days, and delete them after 180 days. Each execution applies only the highest-priority matching action. + +###### Image states that skip rule evaluation + +Image Builder skips images in certain states to prevent duplicate actions: + + * **Deprecate rule** – Image Builder skips images that are already deprecated, disabled, failed, or canceled. + + * **Disable rule** – Image Builder skips images that are already disabled, failed, or canceled. + + * **Delete rule** – Image Builder evaluates images in any state for deletion, subject to retention rules and exclusions. + + + @@ -44 +80,9 @@ For container images, this rule deletes the Image Builder container image resour - * View lifecycle management rule details for a policy + * Tags as resource selectors vs. exclusion rules + + * How retention is calculated + + * How lifecycle actions affect associated resources + + * Allowed resource state transitions + + * View rule details for a lifecycle policy @@ -51 +95,175 @@ For container images, this rule deletes the Image Builder container image resour -The following exclusion rules define exceptions to the lifecycle rules for AMIs. AMIs that meet the criteria specified by the exclusion rules are excluded from lifecycle actions. You can configure exclusion rules in the AWS Management Console or by using the API and AWS CLI. +Exclusion rules protect specific AMIs from lifecycle actions. Configure exclusion rules in the AWS Management Console, the API, or the AWS CLI. + +Lifecycle policies support these exclusion rule types: + + * **Tag-based exclusion** – Excludes Image Builder image resources with specific tags (up to 50 tags). For more information about how tags work at different resource levels, see Tags as resource selectors vs. exclusion rules. + + * **Public AMI exclusion** – Excludes publicly shared AMIs. + + * **Last launched exclusion** – Excludes AMIs that launched an instance within a specified time period. + +###### Note + +Amazon EC2 reports the last launched time with a 24-hour delay. Launches within the last 24 hours might not be reflected when the exclusion check runs. + + * **Region exclusion** – Excludes AMIs in specific AWS Regions. + + * **Shared account exclusion** – Excludes AMIs shared with specific AWS accounts. + + + + +###### Note + +Image Builder skips images with a build in progress (pending, creating, building, importing, testing, distributing, or integrating state). Image Builder evaluates these images in the next scheduled run. + +###### AMI exclusion rule evaluation order + +EC2 Image Builder evaluates AMI-level exclusion rules (`exclusionRules.amis`) on the output AMI after determining eligibility for a lifecycle action. These rules apply to the Amazon EC2 AMI resource, not the Image Builder image resource. Retention counting runs separately. An excluded AMI does not consume a retention slot. Image Builder checks conditions in order and skips the AMI at the first match: + + 1. **Region exclusion** – Checks whether the AMI is in an excluded Region. + + 2. **Public AMI exclusion** – Checks whether the AMI is public and `isPublic` exclusion is enabled. + + 3. **Tag exclusion** – Checks whether the AMI has tags matching the exclusion tag map. + + 4. **Shared account exclusion** – Checks whether the AMI is shared with accounts listed in the exclusion. + + 5. **Last launched exclusion** – Checks whether the AMI launched within the excluded time window. + + + + +In execution resource details, skipped AMIs display a `SKIPPED` status with a reason that indicates which exclusion condition matched. + +## Tags as resource selectors vs. exclusion rules + +Tags serve two distinct purposes in lifecycle policies. Each tag mechanism operates on a specific resource level: + + * **Image Builder image** – The Image Builder resource that tracks a build (ARN format: `arn:aws:imagebuilder:`region`:`account`:image/`name`/`version``). Manage tags on this resource through Image Builder. + + * **Output AMI or container image** – The underlying Amazon EC2 AMI or Amazon ECR container image that Image Builder produces. Manage tags on these resources through Amazon EC2 or Amazon ECR respectively. + + + + +**Tags as resource selectors** (policy scope) + + +Tag-based resource selection evaluates tags on the _Image Builder image resource only_ , not on output AMIs or containers. Image Builder uses these tags to _find_ resources the policy applies to. + +Configure tag-based resource selection in the `resourceSelection.tagMap` field. Each entry is a key-value pair. The policy selects Image Builder images matching _any_ specified tag key-value pair (OR logic). Image Builder does not evaluate images without matching tags. + +**Tags as exclusion rules** (rule-level exceptions) + + +Exclusion tags work in the opposite direction. After Image Builder selects resources based on the policy scope, it checks each resource against exclusion rules _before_ taking any action. Configure exclusion tags at two levels, each operating on a different resource type: + +`exclusionRules.tagMap` + + +Evaluates tags on the _Image Builder image resource only_. Does _not_ check tags on underlying AMIs or containers. If an Image Builder image tag matches an entry (exact key and value match), Image Builder skips the image and all associated output resources. + +`exclusionRules.amis.tagMap` + + +Evaluates tags on the _output AMI_ (the Amazon EC2-level resource) during associated resource processing. Use this to exclude specific output AMIs based on their Amazon EC2 tags (for example, tags applied through distribution settings or directly through Amazon EC2). + +###### Important + +Resource selection and `exclusionRules.tagMap` do not evaluate tags on output AMIs (Amazon EC2 tags) or containers (Amazon ECR tags). To exclude output AMIs based on Amazon EC2 tags, use `exclusionRules.amis.tagMap`. + +###### Example Tag selector and exclusion working together + +A policy with these settings: + + * Resource selection tag: `Environment: Production` (evaluated on Image Builder image resources) + + * Image-level exclusion tag (`exclusionRules.tagMap`): `Retain: True` (evaluated on Image Builder image resources) + + * AMI-level exclusion tag (`exclusionRules.amis.tagMap`): `SharedWith: Partner` (evaluated on output AMIs) + + + + +Image Builder performs these steps: + + 1. **Resource selection** – Image Builder finds all Image Builder image resources tagged `Environment: Production`. + + 2. **Image-level exclusion** – Image Builder checks each selected Image Builder image for the tag `Retain: True`. Image Builder skips images with this tag, including their output resources. + + 3. **AMI-level exclusion** – Image Builder checks output AMIs (Amazon EC2 resources) of remaining images for the tag `SharedWith: Partner`. AMIs with this tag are skipped. + + + + +## How retention is calculated + +When you configure retention settings for delete rules, the AGE and COUNT filters evaluate against your _Image Builder image resources_ , not directly against output AMIs or containers. + +###### Important + +The AGE filter uses the Image Builder image resource creation date (set once the build completes), not the output AMI or container creation date. The COUNT filter counts Image Builder image resources per recipe version, not output AMIs or containers. + +Retention calculation depends on how you specify recipe versions in your policy scope: + +Specific version (for example, `1.0.0`) + + +Retention count applies to Image Builder images built with that exact recipe version. Image Builder retains the newest images (by creation date) first. + +Wildcard version pattern (for example, `1.x.x`) + +