Why an "untagged" lifecycle rule can remove parts of a tagged image built for several platforms in Amazon ECR and how to check your policy by hand before it does.

Lifecycle policies are how most of us keep an ECR bill sane. A rule like "expire untagged images older than 14 days" sounds harmless. For years it was.

Then we started building for linux/amd64 and linux/arm64 with Buildx. Buildx also adds provenance attestations by default. Now that same rule can remove pieces of an image you still deploy. You find out when a pull fails. Usually during a scale out or a rollback, which is the worst time.

Here is why it happens and how I check a policy before I trust it.

One tag, many rows

A push for several platforms does not create one image in ECR. It creates several manifests:

  • an image index (also called a manifest list). This is the only row with your tag.
  • one image manifest per platform, like linux/amd64 and linux/arm64. These hold the real layers.
  • often an attestation manifest per platform for provenance or an SBOM. In the index these show up with platform unknown/unknown.
  • if you sign images you may also get signatures and other OCI referrers.

In the console and in describe-images every one of these is its own row. Only the index has a tag. So the platform images and attestations look like random untagged images.

Lifecycle rules count rows. A rule with "tagStatus": "untagged" selects every row with no tag. That includes the platform images your tagged index points to. Once they expire the tag still exists. Pulling it for that platform does not work anymore.

This is not theory. In containers-roadmap #1596 one user had a count rule remove two versions overnight and another reported a production outage in March 2026 after BuildKit started adding provenance rows to every build.

Look at what one tag really contains

The quickest view is Buildx itself:

docker buildx imagetools inspect \ 111122223333.dkr.ecr.us-east-1.amazonaws.com/my-repo:v1.4.0 

You get the index digest and the digest of each platform image and attestation.

Without Docker you can read the index straight from ECR:

aws ecr batch-get-image --repository-name my-repo \ --image-ids imageTag=v1.4.0 \ --accepted-media-types application/vnd.oci.image.index.v1+json \ application/vnd.docker.distribution.manifest.list.v2+json \ --query 'images[0].imageManifest' --output text \ | jq '.manifests[] | {digest, platform, type: .annotations["vnd.docker.reference.type"]}' 

Rows where type is attestation-manifest are attestations. The rest are your platform images.

Now list the untagged rows with their media types:

aws ecr describe-images --repository-name my-repo \ --query 'imageDetails[?imageTags==null].[imageDigest,imageManifestMediaType,artifactMediaType,imagePushedAt]' \ --output table 

Compare the digests. Every untagged digest that appears inside a tagged index is a row you must keep. Do this for every tag you still care about.

ECR's lifecycle preview and where it stops

ECR has a built in preview:

aws ecr start-lifecycle-policy-preview --repository-name my-repo \ --lifecycle-policy-text file://policy.json aws ecr get-lifecycle-policy-preview --repository-name my-repo 

It runs async. You poll until the status is COMPLETE and then get the digests and tags it would expire. It is useful. I run it. But keep its limits in mind:

  • It tells you what would go. It does not tell you what depends on it. Matching expiring digests against indexes is your job.
  • It knows nothing about ECS or Lambda. An image a service still runs looks the same as one nobody uses.
  • It shows today. An age rule that hits your running release next Tuesday does not show up.
  • It is one repository at a time and one preview per repository at a time. Many repos across regions and accounts means a script.
  • It needs ecr:StartLifecyclePolicyPreview. The preview is stored on the AWS side. If you want a role that can only read, leave it out and simulate the rules yourself.

If you simulate, follow ECR's rules. Rules run in rulePriority order. A row is claimed by the first rule whose tag selection fits it and lower priority rules never touch it. tagged rules need tagPrefixList or tagPatternList and a row must match every entry. imageCountMoreThan keeps the newest N rows the rule claimed, by push date. sinceImagePushed expires rows older than N days.

Check what ECS and Lambda run

Before you apply anything, collect the images in use. For ECS services, read the task definitions:

aws ecs describe-services --cluster prod --services api worker \ --query 'services[].taskDefinition' --output text \ | xargs -n1 aws ecs describe-task-definition --query 'taskDefinition.containerDefinitions[].image' --output text --task-definition 

Running tasks report the exact digest they pulled:

aws ecs describe-tasks --cluster prod \ --tasks $(aws ecs list-tasks --cluster prod --desired-status RUNNING --query 'taskArns' --output text) \ --query 'tasks[].containers[].[image,imageDigest]' --output text 

For Lambda functions packaged as container images:

aws lambda get-function --function-name my-fn \ --query 'Code.[ImageUri,ResolvedImageUri]' --output text 

Turn every tag into a digest with describe-images. Then make sure none of those digests are in the preview. Also check the platform images under them. A running v1.2.0 is broken just as badly if its arm64 image goes.

A safer policy

There is no untagged rule that is safe in every repo. The idea that works for me: untagged rows must outlive the tagged images that point to them. That only holds if every tagged image in the repo has an age limit shorter than the untagged rule.

So I keep short lived builds and releases apart. In a repo for CI builds:

{ "rules": [ { "rulePriority": 1, "description": "Branch and dev builds go after 30 days", "selection": { "tagStatus": "tagged", "tagPatternList": ["dev-*"], "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 30 }, "action": {"type": "expire"} }, { "rulePriority": 2, "description": "Untagged rows go only after their parents can be gone", "selection": { "tagStatus": "untagged", "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 45 }, "action": {"type": "expire"} } ] } 

When a dev-* index expires at 30 days its children become orphans. The untagged rule cleans them up later. The 14 day gap is the margin.

This only works if every tag in that repo matches dev-*. Any other tag has no age limit here, so its children get hit at 45 days. That is why releases live in their own repo. There I keep tagged releases with a count rule and either no untagged rule at all or one with an age longer than my oldest kept release. I check that age again whenever I raise the count.

Two more things help. If you do not need provenance attestations, docker buildx build --provenance=false stops creating them. And never use tagStatus: any with a count rule on a repo that holds images for several platforms. It counts platform images and attestations as images.

Run the preview again after every policy change. In every region and every account.

Disclosure: I built a tool for this

Doing all of the above for a few dozen repos got old, so I built ECR Image Inspector and Lifecycle Policy Dry-Run. It connects with a CloudFormation role that can only read ECR, ECS and Lambda metadata. It groups each repo into index, platform images and attestations, signatures and SBOMs. It simulates your real policy with the rules described above without calling the preview API. Then it shows what would expire today and in the next 7 days. It warns when a row is used by an ECS service, a running task or a Lambda function. It also warns when a row belongs to a tagged image you keep. It suggests a safer policy and checks it the same way. A daily scan alerts on Slack or email. There is a free trial. I built it, so take my take with that in mind. The CLI steps above are all you strictly need.