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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{ "rules": [ { "rulePriority": integer, "description": "string", "selection": { "tagStatus": "tagged"|"untagged"|"any", "tagPrefixList": list "countType": "imageCountMoreThan"|"sinceImagePushed", "countUnit": "string", "countNumber": integer }, "action": { "type": "expire" } } ] } |
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?
Prerequisites:
AWS CLI and Docker installed and configured.
Step 1: Create a new ECR repository.
|
1 2 3 4 5 |
## Create a private repository in ECR aws ecr create-repository \ --repository-name my_private_repo \ --image-tag-mutability IMMUTABLE \ --image-scanning-configuration scanOnPush=false |
Step 2: Create a new docker image with tag version 1 and push to your ECR repository.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
## Create a Dockerfile cat << EOF > Dockerfile FROM ubuntu:18.04 # Install dependencies RUN apt-get update && \ apt-get -y install apache2 # Install apache and write hello world message RUN echo 'Hello World from v1.0.0!' > /var/www/html/index.html # Configure apache RUN echo '. /etc/apache2/envvars' > /root/run_apache.sh && \ echo 'mkdir -p /var/run/apache2' >> /root/run_apache.sh && \ echo 'mkdir -p /var/lock/apache2' >> /root/run_apache.sh && \ echo '/usr/sbin/apache2 -D FOREGROUND' >> /root/run_apache.sh && \ chmod 755 /root/run_apache.sh EXPOSE 80 CMD /root/run_apache.sh EOF ## Create a docker image docker build -t myimage:dev-v1.0.0 . ## Check if the docker image was created successfully docker images --filter reference=myimage:dev-v1.0.0 ## Authenticate yourself to the AWS ECR registry REGION='ap-south-1' && AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r .Account) && aws ecr get-login-password \ --region $REGION | docker login --username AWS \ --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com ## TAG you docker image form ECR private repository docker tag myimage:dev-v1.0.0 $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/my_private_repo:dev-v1.0.0 ## PUSH a docker image from a private ECR repository docker push $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/my_private_repo:dev-v1.0.0 ## List image tags in the repository aws ecr list-images \ --repository-name my_private_repo | jq -r .imageIds[].imageTag ## returns dev-v1.0.0 |
Step 3: Create a new tag version of your docker image and push to ECR repository.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
## Update the Dockerfile cat << EOF > Dockerfile FROM ubuntu:18.04 # Install dependencies RUN apt-get update && \ apt-get -y install apache2 # Install apache and write hello world message RUN echo 'Hello World from v2.0.0!' > /var/www/html/index.html # Configure apache RUN echo '. /etc/apache2/envvars' > /root/run_apache.sh && \ echo 'mkdir -p /var/run/apache2' >> /root/run_apache.sh && \ echo 'mkdir -p /var/lock/apache2' >> /root/run_apache.sh && \ echo '/usr/sbin/apache2 -D FOREGROUND' >> /root/run_apache.sh && \ chmod 755 /root/run_apache.sh EXPOSE 80 CMD /root/run_apache.sh EOF ## Create a new docker image docker build -t myimage:dev-v2.0.0 . ## TAG you docker image form ECR private repository docker tag myimage:dev-v2.0.0 $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/my_private_repo:dev-v2.0.0 ## PUSH a docker image from a private ECR repository docker push $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/my_private_repo:dev-v2.0.0 ## List image tags in the repository aws ecr list-images \ --repository-name my_private_repo | jq -r .imageIds[].imageTag ## returns dev-v1.0.0 and dev-v2.0.0 |
Step 4: Create a lifecycle policy definition file.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
## Create a lifecycle policy definition file cat << EOF > mypolicy.json { "rules": [ { "rulePriority": 1, "description": "maintain only one image", "selection": { "tagStatus": "tagged", "tagPrefixList": ["dev"], "countType": "imageCountMoreThan", "countNumber": 1 }, "action": { "type": "expire" } } ] } EOF |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
## Create a lifecycle policy preview aws ecr start-lifecycle-policy-preview \ --repository-name my_private_repo \ --lifecycle-policy-text file://mypolicy.json ## Get the images that will expire if we apply the lifecycle policy aws ecr get-lifecycle-policy-preview \ --repository-name my_private_repo ## "previewResults": [ ## { ## "action": { ## "type": "EXPIRE" ## }, ## "imageTags": [ ## "dev-v1.0.0" ## ], ## "appliedRulePriority": 1, ## "imageDigest": "sha256: ## "imagePushedAt": 1646145263.0 ## } ## ] |
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.
|
1 2 3 4 5 6 7 8 |
## Create a lifecycle policy in ECR aws ecr put-lifecycle-policy \ --repository-name my_private_repo \ --lifecycle-policy-text file://mypolicy.json ## Get the life cycle policy details aws ecr get-lifecycle-policy \ --repository-name my_private_repo |
You can also create the lifecycle policy or view the lifecycle policy events from AWS management console under ECR service.
Note: If may take up to 24 hours before the image actually get expired and removed from the repository.
Step 7: Clean up.
|
1 2 3 4 |
## Delete the private repository aws ecr delete-repository \ --repository-name my_private_repo \ --force |
Hope you have enjoyed this article, to get more details on AWS ECR, please follow below link.
https://docs.aws.amazon.com/ecr/index.html