# Automate the cleanup of images by using lifecycle policies in Amazon ECR
<a name="LifecyclePolicies"></a>

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 can be archived or expired based on the criteria specified in the lifecycle policy 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](logging-using-cloudtrail.md).

## How lifecycle policies work
<a name="lifecycle-policy-howitworks"></a>

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](logging-using-cloudtrail.md).

The following diagram shows the lifecycle policy workflow.

![\[Diagram showing the process for evaluating and applying a lifecycle policy.\]](http://docs.aws.amazon.com/AmazonECR/latest/userguide/images/lifecycle-policy.png)


1. Create one or more test rules.

1. Save the test rules and run the preview.

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

1. The lifecycle policy evaluator then applies the rules, based on rule priority, and displays which images in the repository are set to be expired or archived. A lower rule priority number means higher priority. For example, a rule with priority 1 takes precedence over a rule with priority 2.

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

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

1. Once the lifecycle policy is created, you should expect that images are expired or archived within 24 hours after they meet the expiration criteria.

### Lifecycle policy evaluation rules
<a name="lp_evaluation_rules"></a>

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](lifecycle_policy_examples.md).
+ When reference artifacts are present in a repository, Amazon ECR lifecycle policies automatically expire or archive those artifacts within 24 hours of the deletion or archival of the subject image.
+ 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 or archived by exactly one or zero rules.
+ An image that matches the tagging requirements of a rule cannot be expired or archived 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 or archived.
+ The set of all rules selecting a specific storage class must contain a unique set of prefixes.
+ Only one rule selecting a specific storage class is allowed to select untagged images.
+ If an image is referenced by a manifest list, it cannot be expired or archived without the manifest list being deleted or archived first.
+ Expiration is always ordered by `pushed_at_time` or `transitioned_at_time` and always expires older images before newer ones. If an image was archived and then restored at any point in the past, the image's `last_activated_at` is used instead of `pushed_at_time`.
+ 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. An image is successfully matched if all of the tags in the `tagPatternList` or `tagPrefixList` value are matched against any of the image's tags. 
+ 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 image-tags whose name begins with `prod` such as `prod`, `prod1`, or `production-team1`. Similarly, if a filter of `*prod*` is applied, it would match image-tags 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 wildcard filters in the `tagPrefixList` value are matched against any of the image's tags.
+ The `countUnit` parameter is only used if `countType` is `sinceImagePushed`, `sinceImagePulled`, or `sinceImageTransitioned`.
+ 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 or archived.
+ With `countType = sinceImagePushed`, all images whose `pushed_at_time` is older than the specified number of days based on `countNumber` are expired or archived.
+ With `countType = sinceImagePulled`, all images whose `last_recorded_pulltime` is older than the specified number of days based on `countNumber` are archived. If an image was never pulled, the image's `pushed_at_time` is used instead of the `last_recorded_pulltime`. If an image was archived and then restored at any point in the past, but never pulled since the image was restored, the image's `last_activated_at` is used instead of the `last_recorded_pulltime`.
+ With `countType = sinceImageTransitioned`, all archived images whose `last_archived_at` is older than the specified number of days based on `countNumber` are expired.
+ Expiration is always ordered by `pushed_at_time` and always expires older images before newer ones.