Configure ECR Lifecycle Policies for Image Expiration and Storage Control

Overview

Implement lifecycle policies for Amazon ECR repositories to automatically expire untagged and old container images, keeping storage usage under control while preserving the images you need for deployments, rollbacks, and compliance.

The plan first inventories your ECR repositories and images, then guides you through choosing which repositories to manage and how to define retention rules. It then applies lifecycle policies that reflect your decisions and finishes by validating that the effective policies match your intended behavior.

Execution Details

Assessment

Inventory ECR repositories and existing lifecycle policies

First, all in-scope AWS accounts and regions are identified, and every ECR repository in those regions is enumerated. For each repository, key attributes such as name, ARN, account/registry ID, region, URI, and available metadata/tags (environment, application, owner, etc.) are captured.

The plan checks whether each repository already has a lifecycle policy configured. Existing lifecycle policies are collected in full and summarized by their rules, priorities, tag handling (tagged/untagged/any), tag prefixes, selection criteria (age- or count-based), and actions (such as expire). Repositories with no lifecycle policy are clearly flagged. All of this information is stored in a structured format for later steps.

Inventory images in repositories with tags, age, and size

Using the repository list, the plan inventories all images within each repository. For every image, it records the digest, associated tags, push time, and size. Untagged images are explicitly identified, and relationships where multiple tags point to the same digest are preserved.

Per-repository summaries are generated, including total number of images, counts of tagged vs. untagged images, and approximate total storage consumed. Images may also be roughly grouped by age (for example, recent vs. older images) to help you choose appropriate retention thresholds. The resulting inventory and summaries are stored for user review.

User: Select repositories for lifecycle policy management

You are presented with the repository inventory, including whether each repository already has a lifecycle policy, its metadata (such as environment and owner), and high-level image statistics (image counts, untagged counts, storage usage).

Using this information, you review which repositories are actively used, which are deprecated or for testing, and decide where lifecycle policies should be created, updated, or left unchanged. You can explicitly mark any repositories as out of scope and note why they are excluded.

Optionally, you can group repositories with similar retention needs (for example, production vs. non-production or by application family) to simplify rule definition. The outcome is a structured list showing, for each in-scope repository, whether it will receive a new policy, have an existing policy updated, or be left as-is.

User: Define per-repository image retention rules

For the repositories you selected, you then define concrete lifecycle retention rules. Using the detailed image inventories and summaries, the plan guides you through decisions such as:

• How to handle untagged images (for example, expire them after a number of days, or keep only the most recent N untagged images).
• How to handle old tagged images (for example, expire images older than a specified number of days, or keep only the last N images by tag or per repository).
• Which tags or prefixes (such as prod, stable, latest) should be exempt or treated with more conservative retention.
• Whether to apply different rules to different classes of images within a repository (for example, one rule for feature-branch tags, another for release tags, plus a separate rule for untagged images).

You also define rule priorities and ordering so that specific rules override general ones and ensure alignment with any organizational or compliance requirements. The result is a clear, structured specification for each repository, including descriptions, tag status, tag prefixes, age- or count-based criteria, thresholds, and actions (expire), ready to be translated into ECR lifecycle policies.

Configuration

Apply lifecycle policies to selected ECR repositories

Using the list of selected repositories and your defined retention rules, the plan constructs lifecycle policy documents per repository. For each:

• It determines whether a policy already exists and whether it should be replaced or adjusted.
• It builds a set of rules with unique priorities, clear descriptions, tag status (tagged, untagged, or any), tag prefixes where applicable, and age/count-based selection criteria.
• It ensures rules that combine age and count retention do not conflict and that their combined effect matches your intent.

The lifecycle policies are then attached to or updated on the target repositories. If required for change tracking, the previous policy text is archived alongside the new version. After application, the current policy on each repository is retrieved and compared with the intended definition to confirm they match. Any failures or partial updates are recorded, and a configuration summary is produced that lists each repository, whether its policy was created or updated, and references to the final rules applied.

Validation

Validate lifecycle policies on ECR repositories

Finally, the plan validates that the configured lifecycle policies truly implement the intended retention behavior. For each repository where a policy was created or updated, it retrieves the active lifecycle policy and compares it to your original rule specifications, checking:

• The correct number of rules and expected rule priorities.
• Presence and accuracy of rule descriptions.
• Correct tag status, tag prefixes, and age/count thresholds.
• Proper handling of untagged image cleanup where required.
• Proper cleanup of old tagged images where required.
• Correct preservation of any tags or prefixes that should not be expired.

Where feasible, the plan initiates a lifecycle policy evaluation or preview for selected repositories, verifying that the images marked for expiration match your expectations. Any mismatches, anomalies, or unexpected selections are documented for follow-up. A final validation report summarizes, per repository, whether its lifecycle policy accurately reflects the intended retention rules and highlights any repositories that need further adjustments.