Lifecycle policies
Amazon ECR lifecycle policies enable you to specify the lifecycle management of images in a repository. A lifecycle policy is a set of one or more rules, where each rule defines an action for Amazon ECR. The actions apply to images that contain tags prefixed with the given strings. This allows the automation of cleaning up unused images, for example expiring images based on age or count. You should expect that after creating a lifecycle policy the affected images are expired within 24 hours.
Topics
Lifecycle policy template
The contents of your lifecycle policy is evaluated before being associated with a repository. The following is the JSON syntax template for the lifecycle policy. For lifecycle policy examples, see Examples of lifecycle policies.
{
"rules": [
{
"rulePriority": integer
,
"description": "string
",
"selection": {
"tagStatus": "tagged
"|"untagged
"|"any
",
"tagPrefixList": list<string>
,
"countType": "imageCountMoreThan
"|"sinceImagePushed
",
"countUnit": "string
",
"countNumber": integer
},
"action": {
"type": "expire"
}
}
]
}
The tagPrefixList
parameter is only used if tagStatus
is
tagged
. The countUnit
parameter is only used if
countType
is sinceImagePushed
. The
countNumber
parameter is only used if countType
is set
to imageCountMoreThan
.
Lifecycle policy parameters
Lifecycle policies are split into the following parts:
Topics
Rule priority
rulePriority
-
Type: integer
Required: yes
Sets the order in which rules are evaluated, lowest to highest. A lifecycle policy rule with a priority of
1
will be acted upon first, a rule with priority of2
will be next, and so on. When you add rules to a lifecycle policy, you must give them each a unique value forrulePriority
. Values do not need to be sequential across rules in a policy. A rule with atagStatus
value ofany
must have the highest value forrulePriority
and be evaluated last.
Description
description
-
Type: string
Required: no
(Optional) Describes the purpose of a rule within a lifecycle policy.
Tag status
tagStatus
-
Type: string
Required: yes
Determines whether the lifecycle policy rule that you are adding specifies a tag for an image. Acceptable options are
tagged
,untagged
, orany
. If you specifyany
, then all images have the rule applied to them. If you specifytagged
, then you must also specify atagPrefixList
value. If you specifyuntagged
, then you must omittagPrefixList
.
Tag prefix list
tagPrefixList
-
Type: list[string]
Required: yes, only if
tagStatus
is set to taggedOnly used if you specified
"tagStatus": "tagged"
. You must specify a comma-separated list of image tag prefixes on which to take action with your lifecycle policy. For example, if your images are tagged asprod
,prod1
,prod2
, and so on, you would use the tag prefixprod
to specify all of them. If you specify multiple tags, only the images with all specified tags are selected.
Count type
countType
-
Type: string
Required: yes
Specify a count type to apply to the images.
If
countType
is set toimageCountMoreThan
, you also specifycountNumber
to create a rule that sets a limit on the number of images that exist in your repository. IfcountType
is set tosinceImagePushed
, you also specifycountUnit
andcountNumber
to specify a time limit on the images that exist in your repository.
Count unit
countUnit
-
Type: string
Required: yes, only if
countType
is set tosinceImagePushed
Specify a count unit of
days
to indicate that as the unit of time, in addition tocountNumber
, which is the number of days.This should only be specified when
countType
issinceImagePushed
; an error will occur if you specify a count unit whencountType
is any other value.
Count number
countNumber
-
Type: integer
Required: yes
Specify a count number. Acceptable values are positive integers (
0
is not an accepted value).If the
countType
used isimageCountMoreThan
, then the value is the maximum number of images that you want to retain in your repository. If thecountType
used issinceImagePushed
, then the value is the maximum age limit for your images.
Action
type
-
Type: string
Required: yes
Specify an action type. The supported value is
expire
.
Lifecycle policy evaluation rules
The lifecycle policy evaluator is responsible for parsing the plaintext JSON and applying it to the images in the specified repository. The following rules should be noted when creating a lifecycle policy:
-
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.
-
Expiration is always ordered by
pushed_at_time
, and always expires older images before newer ones. -
When using the
tagPrefixList
, an image is successfully matched if all of the tags in thetagPrefixList
value are matched against any of the image's tags. -
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.