Amazon ECR – Consider Using a Lifecycle Policy

An Amazon ECR lifecycle policy is a set of rules that automatically expires container images in an Amazon Elastic Container Registry (Amazon ECR) repository. Without an Amazon ECR lifecycle policy, every pushed image stays in the repository and is billed as storage indefinitely. Apply one to every repository that receives images from a CI/CD pipeline, with rules that select images by age, count, or tag.

Policy at a Glance

Why This Policy Matters

How It Helps Reduce Cloud Costs

Amazon ECR bills private repository storage per GB-month for every image layer it holds. AWS lists the price at $0.10 per GB-month.

Amazon ECR never deletes images on its own. A repository with no lifecycle policy keeps every build ever pushed to it.

CI/CD pipelines make this worse. A pipeline that builds an image on every commit can push dozens of images per day to one repository.

Most of those images are never deployed again after the next build replaces them. Retagging also leaves the previous image behind as an untagged image, which still consumes billed storage.

This is a common source of silent storage growth. The Amazon ECR bill rises month after month, while the set of images actually in use stays small.

An Amazon ECR lifecycle policy fixes this at the repository level. It expires images that match its rules, so Amazon ECR storage tracks what teams actually run.

Potential Savings

Amazon ECR lifecycle policy savings scale with how many images a pipeline pushes and how large those images are.

Consider a repository holding 1 TB of images. At $0.10 per GB-month, that repository costs about $100 per month in storage.

Suppose a lifecycle policy expires images older than 30 days and keeps only recent releases, shrinking the repository to 100 GB. Storage drops to about $10 per month, a reduction of about 90%.

These figures use AWS list prices at the time of writing and are illustrative. The per-repository number is often modest. The value comes from applying the Amazon ECR lifecycle policy to every repository, since unmanaged repositories grow without limit.

Implementation Guide

Infrastructure-as-Code Example (Terraform)

The following examples show an Amazon ECR repository with no lifecycle policy, and the corrected configuration.

Non-compliant configuration: Amazon ECR repository with no lifecycle policy

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

Every image pushed to acme-api stays in the repository permanently. Nothing in this configuration ever removes an image, so billed storage grows with every build.

This configuration increases costs without improving reliability, since old builds are rarely, if ever, redeployed.

Compliant configuration: Amazon ECR repository with a lifecycle policy

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

resource "aws_ecr_lifecycle_policy" "api" {
  repository = aws_ecr_repository.api.name

  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Keep the 30 most recent release images"
        selection = {
          tagStatus     = "tagged"
          tagPrefixList = ["v"]
          countType     = "imageCountMoreThan"
          countNumber   = 30
        }
        action = {
          type = "expire"
        }
      },
      {
        rulePriority = 2
        description  = "Expire untagged images 14 days after push"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 14
        }
        action = {
          type = "expire"
        }
      }
    ]
  })
}

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

resource "aws_ecr_lifecycle_policy" "api" {
  repository = aws_ecr_repository.api.name

  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Keep the 30 most recent release images"
        selection = {
          tagStatus     = "tagged"
          tagPrefixList = ["v"]
          countType     = "imageCountMoreThan"
          countNumber   = 30
        }
        action = {
          type = "expire"
        }
      },
      {
        rulePriority = 2
        description  = "Expire untagged images 14 days after push"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 14
        }
        action = {
          type = "expire"
        }
      }
    ]
  })
}

resource "aws_ecr_repository" "api" {
  name                 = "acme-api"
  image_tag_mutability = "MUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }
}

resource "aws_ecr_lifecycle_policy" "api" {
  repository = aws_ecr_repository.api.name

  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Keep the 30 most recent release images"
        selection = {
          tagStatus     = "tagged"
          tagPrefixList = ["v"]
          countType     = "imageCountMoreThan"
          countNumber   = 30
        }
        action = {
          type = "expire"
        }
      },
      {
        rulePriority = 2
        description  = "Expire untagged images 14 days after push"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 14
        }
        action = {
          type = "expire"
        }
      }
    ]
  })
}

Rule 1 keeps the 30 most recent images with a tag starting with v and expires older release images. Rule 2 expires untagged images 14 days after they were pushed.

Amazon ECR applies rules in priority order, with lower numbers first. Each image is expired by at most one rule.

The policy argument takes a JSON string, so jsonencode keeps the Amazon ECR lifecycle policy readable and validated by Terraform. The aws_ecr_lifecycle_policy_document data source is an alternative for teams that prefer typed blocks.

Step-by-Step Fix Instructions

1. List every aws_ecr_repository resource in Terraform and check whether each one has a matching aws_ecr_lifecycle_policy resource.

2. Agree on a tagging convention per repository, such as release tags with a v prefix, so rules can protect deployable images.

3. Add an aws_ecr_lifecycle_policy resource for each repository. Start with an untagged-image rule and a count-based rule for release tags.

4. Run the lifecycle policy preview in the Amazon ECR console or with the AWS CLI. Confirm that no image currently deployed would be expired.

5. Run terraform plan and confirm the change only adds lifecycle policy resources.

6. Apply the change. AWS expires matching images within 24 hours after they meet the rule criteria.

7. Add Infracost to CI/CD so any new Amazon ECR repository without a lifecycle policy is flagged in the pull request before merge.

Best Practices

• Make the Amazon ECR lifecycle policy a default in every shared Terraform module that creates an aws_ecr_repository. Let teams change thresholds, not remove the policy.

• Always include a rule for untagged images. Untagged images are almost never deployed directly and accumulate fastest.

• Use count-based rules (imageCountMoreThan) for release tags, so a fixed rollback window is always available.

• Use shorter retention for development and feature-branch repositories than for production repositories.

• Run the lifecycle policy preview before every rule change. An overly broad rule expires images permanently.

Tools and Scripts

How does Infracost detect missing Amazon ECR lifecycle policies automatically?

The Amazon ECR lifecycle policy check is available in Infracost, including in the free trial. When Infracost runs in CI/CD, it scans Terraform in each pull request. Infracost flags Amazon ECR repositories defined without a lifecycle policy directly in the PR comment.

This catches the gap when the fix is a few lines in the same pull request. Infracost also finds existing repositories already in violation across the codebase. FinOps and platform teams can then burn down that backlog over time and measure progress as the count of non-compliant repositories falls.

To check whether a repository already has a lifecycle policy with the AWS CLI:

aws ecr get-lifecycle-policy --repository-name

aws ecr get-lifecycle-policy --repository-name

aws ecr get-lifecycle-policy --repository-name

To preview which images a policy would expire before applying it:

aws ecr start-lifecycle-policy-preview \
  --repository-name acme-api \
  --lifecycle-policy-text file://policy.json

aws ecr get-lifecycle-policy-preview --repository-name

aws ecr start-lifecycle-policy-preview \
  --repository-name acme-api \
  --lifecycle-policy-text file://policy.json

aws ecr get-lifecycle-policy-preview --repository-name

aws ecr start-lifecycle-policy-preview \
  --repository-name acme-api \
  --lifecycle-policy-text file://policy.json

aws ecr get-lifecycle-policy-preview --repository-name

Examples of Impact

Illustrative example: build-per-commit pipeline. A platform team builds and pushes an image for every commit to a busy service repository. After a year, the Amazon ECR repository holds thousands of images, almost all untagged or superseded.

An Amazon ECR lifecycle policy that keeps the last 30 release images and expires untagged images after 14 days fixes this. The repository shrinks to a small fraction of its size.

Build-per-commit repositories are where this policy pays off fastest, because they grow with every merge.

Illustrative example: feature-branch repositories. A team creates an Amazon ECR repository per microservice and pushes feature-branch images to each. Nobody cleans them up after branches merge.

A shared Terraform module that attaches a rule expiring feature- tagged images 7 days after push fixes every repository in one change.

(These are illustrative, composite scenarios, not specific customer accounts.)

Considerations and Caveats

• Expiration is permanent. Amazon ECR lifecycle policies delete expired images. Protect anything a workload might still pull, including rollback targets.

• Rules do not check whether an image is running. An imageCountMoreThan or sinceImagePushed rule expires matching images even if a service still references them.

• Manifest lists hold their images. AWS does not expire an image referenced by a manifest list until the manifest list itself is removed. This can delay savings for multi-architecture images.

• Archive is a separate option. Amazon ECR lifecycle policies can also transition images to an archive storage class instead of expiring them. Check current archive pricing before relying on it for savings.

• Storage only. An Amazon ECR lifecycle policy reduces storage charges. It does not change data transfer charges for image pulls.

Related Policies and Concepts

• Amazon S3 - consider deleting or moving old objects to a cheaper storage class: the Object Storage policy that applies lifecycle rules to current S3 objects, the same retention discipline applied to object storage.

• Amazon S3 - consider deleting or moving non-current object versions to a cheaper storage class: a companion Object Storage policy that removes superseded S3 object versions, which accumulate the same way superseded container images do.

• Amazon S3 - consider deleting incomplete multi-part uploads: an Object Storage policy that removes S3 storage that never appears in normal listings, much like untagged Amazon ECR images.

• Azure Storage Accounts - consider using a lifecycle policy for blob storage: the Azure policy that uses lifecycle management rules to tier or delete blobs automatically.

• Amazon CloudWatch - consider using a retention policy to reduce storage costs: the same retention principle applied to CloudWatch Logs log groups.

Frequently Asked Questions (FAQs)

Is this policy supported in Infracost?

Yes. The Amazon ECR lifecycle policy check is supported in Infracost and available in the free trial. Infracost flags Amazon ECR repositories defined in Terraform without a lifecycle policy, so the team can add one before the pull request merges.

Can this policy be customized?

Yes. The Amazon ECR lifecycle policy itself is fully configurable. Teams choose the tag filters, count type, and retention threshold for each rule. A common setup keeps the last 30 release images and expires untagged images after 14 days.

Does Infracost automatically fix violations?

No. Infracost reports Amazon ECR repositories that have no lifecycle policy. The fix is an aws_ecr_lifecycle_policy resource that the team adds through a Terraform pull request, reviews, and merges.

Is this policy cloud-agnostic?

No. This policy targets Amazon ECR and the aws_ecr_lifecycle_policy resource in the Terraform AWS provider. Other container registries offer similar cleanup rules, but the resource names and policy formats differ.

Does an Amazon ECR lifecycle policy delete images that are still in use?

An Amazon ECR lifecycle policy expires every image that matches its rules. Count-based and push-age rules do not check whether a workload still runs the image. Protect deployed images with a tagged rule that keeps a fixed number of recent release tags. Run the lifecycle policy preview before applying the policy.

How quickly does an Amazon ECR lifecycle policy remove images?

AWS expires images within 24 hours after they meet the criteria of an Amazon ECR lifecycle policy rule. Storage charges for an expired image stop once Amazon ECR removes it.

How often should I review Amazon ECR lifecycle policy compliance?

Teams running Infracost in CI/CD get an Amazon ECR lifecycle policy check on every pull request that adds or changes a repository. For existing repositories, a quarterly review of repository sizes and lifecycle rules is a reasonable cadence.