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.
-
Create one or more test rules.
-
Save the test rules and run the preview.
-
The lifecycle policy evaluator goes through all of the rules and marks the images that each rule affects.
-
The lifecycle policy evaluator then applies the rules, based on rule priority, and displays which images in the repository are set to be expired.
-
Review the results of the test, ensuring that the images that are marked to be expired are what you intended.
-
Apply the test rules as the lifecycle policy for the repository.
-
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
ortagPrefixList
, but not both. However, a lifecycle policy may contain multiple rules where different rules use both pattern and prefix lists. An image is successfully matched if all of the tags in thetagPatternList
ortagPrefixList
value are matched against any of the image's tags. -
The
tagPatternList
ortagPrefixList
parameters may only used if thetagStatus
istagged
. -
When using
tagPatternList
, an image is successfully matched if it matches the wildcard filter. For example, if a filter ofprod*
is applied, it would match image-tags whose name begins withprod
such asprod
,prod1
, orproduction-team1
. Similarly, if a filter of*prod*
is applied, it would match image-tags whose name containsprod
such asrepo-production
orprod-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 wildcard filters in thetagPrefixList
value are matched against any of the image's tags. -
The
countUnit
parameter is only used ifcountType
issinceImagePushed
. -
With
countType = imageCountMoreThan
, images are sorted from youngest to oldest based onpushed_at_time
and then all images greater than the specified count are expired. -
With
countType = sinceImagePushed
, all images whosepushed_at_time
is older than the specified number of days based oncountNumber
are expired.