Layer-aware retention sizing

Container Registry Retention Planner

Model shared base layers, changing layers per image, tagged retention, and temporary unreferenced bytes before garbage collection.

Decision guide

Do not multiply every tag by the complete image size

What this tool helps you decide

This planner estimates capacity for a container image workflow where many tags share base layers but each build introduces changing application layers. It separates retained tagged content from unreferenced unique layers that may remain until garbage collection. Use it to test image cadence, retention days, repository count, documented deduplication scope, cleanup delay, reserve, and quota before a registry fills or a managed plan is exceeded.

Before you start

Inspect a representative compressed image manifest and divide bytes into layers reused across the modeled repositories and layers that change for each new image. Count images pushed per repository, not merely tags pointing to the same digest. Verify whether the registry deduplicates shared blobs across a namespace or only within one repository. Record how long tagged images remain and how long unreferenced layers usually wait before actual reclamation. Use current registry usage and documentation rather than assuming deletion behavior.

How the calculation works

Shared layer size is the compressed image size multiplied by the shared percentage. It is counted once across the namespace when that scope is selected, or once per repository otherwise. Unique layer size is the remainder. Retained images equal new images per repository per day multiplied by repositories and retention days. Pending garbage-collection images use the same cadence multiplied by the entered delay. Projected storage adds shared layers, retained unique layers, and pending unique layers, then compares the total with quota after reserve.

How to interpret the results

The retained unique-layer figure shows the footprint controlled directly by image cadence and tag retention. Pending garbage-collection storage shows why deleting tags may not create immediate capacity headroom. Shared base storage reveals the value of layer reuse but should not be treated as universally cross-repository: actual accounting differs. A negative headroom result means the modeled operating cycle exceeds the reserved quota, even if a one-time cleanup temporarily lowers the current display.

Worked example

A 1.4 GB compressed image with 70% shared bytes has a 0.98 GB base and 0.42 GB of changing layers. Four repositories pushing three images each day retain 168 images over 14 days, using 70.56 GB of unique retained layers. A seven-day garbage-collection delay adds 35.28 GB. With namespace-wide base deduplication, projected storage is 106.82 GB. A 500 GB quota with 15% reserved leaves 318.18 GB of modeled headroom.

Assumptions and limitations

This simplified model assumes one representative image shape, one shared-layer fraction, stable cadence, and no reuse among changing layers. It does not parse manifests, distinguish multiple architectures, count signatures or attestations, model package artifacts, reproduce backend object overhead, determine billable usage, or execute cleanup. Tags can share a digest, manifests can reference common layers, and provider deletion behavior can differ. Confirm scope, accounting, retention precedence, and garbage-collection timing in current official documentation.

Next steps

Record the manifest sample and registry scope used. Reduce changing layers by ordering image stages and excluding build context that does not belong in the image. Preserve release and deployed digests before shortening development retention, then confirm reclamation after the cleanup cycle. Use the CI Artifact Retention Planner for job downloads that are not container images and the Runner Disk Capacity Checker for local image, build-context, and workspace peaks during the build itself.