Automate the cleanup of images by using lifecycle policies in Amazon ECR - Amazon ECR
How lifecycle policies work

Automate the cleanup of images by using lifecycle policies in Amazon ECR

Amazon ECR lifecycle policies provide more control over the lifecycle management of images in a private repository. A lifecycle policy contains one or more rules, and each rule defines an action for Amazon ECR. Based on the expiration criteria in the lifecycle policy, images expire based on age or count within 24 hours. When Amazon ECR performs an action based on a lifecycle policy, this action is captured as an event in AWS CloudTrail. For more information, see Logging Amazon ECR actions with AWS CloudTrail.

How lifecycle policies work

A lifecycle policy consists of one or more rules that determine which images in a repository should be expired. When considering the use of lifecycle policies, it's important to use the lifecycle policy preview to confirm which images the lifecycle policy expires before applying it to a repository. Once a lifecycle policy is applied to a repository, you should expect that images become expired within 24 hours after they meet the expiration criteria. When Amazon ECR performs an action based on a lifecycle policy, this is captured as an event in AWS CloudTrail. For more information, see Logging Amazon ECR actions with AWS CloudTrail.

The following diagram shows the lifecycle policy workflow.

Diagram showing the process for evaluating and applying a lifecycle policy.

  1. Create one or more test rules.

  2. Save the test rules and run the preview.

  3. The lifecycle policy evaluator goes through all of the rules and marks the images that each rule affects.

  4. The lifecycle policy evaluator then applies the rules, based on rule priority, and displays which images in the repository are set to be expired.

  5. Review the results of the test, ensuring that the images that are marked to be expired are what you intended.

  6. Apply the test rules as the lifecycle policy for the repository.

  7. Once the lifecycle policy is created, you should expect that images become expired within 24 hours after they meet the expiration criteria.

Lifecycle policy evaluation rules

The lifecycle policy evaluator is responsible for parsing the plaintext JSON of the lifecycle policy, evaluating all rules, and then applying those rules based on rule priority to the images in the repository. The following explains the logic of the lifecycle policy evaluator in more detail. For examples, see Examples of lifecycle policies in Amazon ECR.

  • All rules are evaluated at the same time, regardless of rule priority. After all rules are evaluated, they are then applied based on rule priority.

  • An image is expired by exactly one or zero rules.

  • An image that matches the tagging requirements of a rule cannot be expired by a rule with a lower priority.

  • Rules can never mark images that are marked by higher priority rules, but can still identify them as if they haven't been expired.

  • The set of rules must contain a unique set of tag prefixes.

  • Only one rule is allowed to select untagged images.

  • If an image is referenced by a manifest list, it cannot be expired without the manifest list being deleted first.

  • Expiration is always ordered by pushed_at_time, and always expires older images before newer ones.

  • A lifecycle policy rule may specify either tagPatternList or tagPrefixList, but not both. However, a lifecycle policy may contain multiple rules where different rules use both pattern and prefix lists.

  • The tagPatternList or tagPrefixList parameters may only used if the tagStatus is tagged.

  • When using tagPatternList, an image is successfully matched if it matches the wildcard filter. For example, if a filter of prod* is applied, it would match repositories whose name begins with prod such as prod, prod1, or production-team1. Similarly, if a filter of *prod* is applied, it would match repositories whose name contains prod such as repo-production or prod-team.

    Important

    There is a maximum limit of four wildcards (*) per string. For example, ["*test*1*2*3", "test*1*2*3*"] is valid but ["test*1*2*3*4*5*6"] is invalid.

  • When using tagPrefixList, an image is successfully matched if all of the tags in the tagPrefixList value are matched against any of the image's tags.

  • The countUnit parameter is only used if countType is sinceImagePushed.

  • With countType = imageCountMoreThan, images are sorted from youngest to oldest based on pushed_at_time and then all images greater than the specified count are expired.

  • With countType = sinceImagePushed, all images whose pushed_at_time is older than the specified number of days based on countNumber are expired.