You are currently viewing How to create lifecycle policy in Amazon ECR?

How to create lifecycle policy in Amazon ECR?

  • Post author:
  • Post category:AWS

How to create lifecycle policy in Amazon ECR?

Hello Everyone

Welcome to CloudAffaire and this is Debjeet.

Today we will discuss how to cleanup old docker images using lifecycle policy in AWS ECR with example.

What is lifecycle policy in AWS 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, where each rule defines an action for Amazon ECR. This provides a way to automate the cleaning up of unused images, for example expiring images based on age or count.

How AWS ECR 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 the affected images will expire within 24 hours.

AWS ECR Lifecycle policy elements:

rulePriority (Type: integer, Required: yes):

Sets the order in which rules are applied, lowest to highest. A lifecycle policy rule with a priority of 1 will be applied first, a rule with priority of 2 will be next, and so on. When you add rules to a lifecycle policy, you must give them each a unique value for rulePriority. Values do not need to be sequential across rules in a policy. A rule with a tagStatus value of any must have the highest value for rulePriority and be evaluated last.

description (Type: string, Required: no):

Describes the purpose of a rule within a lifecycle policy.

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, or any. If you specify any, then all images have the rule evaluated against them. If you specify tagged, then you must also specify a tagPrefixList value. If you specify untagged, then you must omit tagPrefixList.

tagPrefixList (Type: list[string], Required: yes, only if tagStatus is set to tagged):

Only 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 as prod, prod1, prod2, and so on, you would use the tag prefix prod to specify all of them. If you specify multiple tags, only the images with all specified tags are selected.

countType (Type: string, Required: yes):

Specify a count type to apply to the images. If countType is set to imageCountMoreThan, you also specify countNumber to create a rule that sets a limit on the number of images that exist in your repository. If countType is set to sinceImagePushed, you also specify countUnit and countNumber to specify a time limit on the images that exist in your repository.

countUnit (Type: string, Required: yes, only if countType is set to sinceImagePushed):

Specify a count unit of days to indicate that as the unit of time, in addition to countNumber, which is the number of days. This should only be specified when countType is sinceImagePushed; an error will occur if you specify a count unit when countType is any other value.

countNumber (Type: integer, Required: yes):

Specify a count number. Acceptable values are positive integers (0 is not an accepted value). If the countType used is imageCountMoreThan, then the value is the maximum number of images that you want to retain in your repository. If the countType used is sinceImagePushed, then the value is the maximum age limit for your images.

type (Type: string, Required: yes):

Specify an action type. The supported value is “expire”.

AWS ECR lifecycle policy syntax:

Enough of theory, let me explain how AWS ECR lifecycle policy works and how to create a lifecycle policy in AWS ECR with an example.

How to create lifecycle policy in Amazon ECR?


AWS CLI and Docker installed and configured.

Step 1: Create a new ECR repository.

Step 2: Create a new docker image with tag version 1 and push to your ECR repository.

Step 3: Create a new tag version of your docker image and push to ECR repository.

Step 4: Create a lifecycle policy definition file.

Now you can directly apply the above lifecycle policy to the ECR repository and expire images as per defined policy. Or you can also run a preview to list the images that will get expired if we apply the lifecycle policy. This is particularly very useful if you have hundreds or thousands of images in your ECR repository and wanted to check which images will get expired if you apply the lifecycle policy.

Step 5: Create a lifecycle preview and get images that will get expired if the lifecycle policy is created.

Note: This does not create the actual lifecycle policy, but only validates which images will get expired if the policy is created.

Observe: Image with tag “dev-v1.0.0” will get expired if we create the policy.

Step 6: Create the lifecycle policy in AWS ECR.

You can also create the lifecycle policy or view the lifecycle policy events from AWS management console under ECR service.

How to create lifecycle policy in Amazon ECR?

Note: If may take up to 24 hours before the image actually get expired and removed from the repository.

Step 7: Clean up.

Hope you have enjoyed this article, to get more details on AWS ECR, please follow below link.