ECR Lifecycle Policies

ECR lifecycle policies automatically expire and remove old, no-longer-needed image versions from a repository based on configurable rules, preventing unbounded accumulation of outdated images and the associated storage cost that would otherwise build up indefinitely.

Defining a Lifecycle Policy

A lifecycle policy specifies rules for which images should be automatically expired, typically based on age or count.

aws ecr put-lifecycle-policy --repository-name myapp --lifecycle-policy-text file://lifecycle-policy.json

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Expire images older than 90 days",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 90
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}

This rule specifically targets untagged images older than 90 days, a common pattern for cleaning up dangling layers left behind by repeated builds without affecting any actually tagged, intentionally retained version.

Why Untagged Images Are a Common Cleanup Target

An untagged image, typically the result of a tag being moved to point at a newer build, often represents content no longer directly referenced by anything, making it a reasonable default target for automatic cleanup.

aws ecr list-images --repository-name myapp --filter tagStatus=UNTAGGED

Reviewing untagged images before relying on automatic cleanup helps confirm the policy is targeting genuinely unneeded content.

Retaining Only a Limited Number of Recent Tagged Versions

A more aggressive policy can also limit how many recent tagged versions are retained, automatically expiring older ones beyond a specified count.

{
  "selection": {
    "tagStatus": "tagged",
    "tagPrefixList": ["v"],
    "countType": "imageCountMoreThan",
    "countNumber": 20
  },
  "action": {
    "type": "expire"
  }
}

Why ECR Lifecycle Policies Matter

Automatic lifecycle management prevents a repository's storage footprint (and associated cost) from growing indefinitely as new images are continuously pushed, without requiring manual, ongoing cleanup effort to keep storage usage reasonable.