Retention policies — keeping your registry from filling the disk · Docker & Containers

A registry stores images; images are composed of layers; layers take disk. Without retention, the registry fills.

That much is obvious. What is not obvious — and what makes registry retention different from every other kind of cleanup — is that deleting things does not free space. There are two separate operations and conflating them is why registries run out of disk while their operators are confident they cleaned up.

Two operations, not one

Deleting a tag or a manifest removes a reference. It rewrites or removes a small link file in the naming tree. Disk usage does not change measurably.

Garbage collection reclaims bytes. It walks the naming tree, builds the set of blobs still reachable, and deletes every blob not in that set.

Nothing is freed until the second step runs. A team can delete a thousand tags, watch the UI empty out, and find the disk exactly as full as it was.

We deleted six months of images and the disk did not move

The sequence is always the same. Storage alerts fire. Someone scripts a bulk deletion of old tags. The registry UI shows the repositories shrinking. df shows nothing.

The first diagnosis is that the deletions did not work — so somebody re-runs them, or escalates to deleting more, or starts questioning the filesystem. The actual answer is that all of it worked exactly as designed and none of it was supposed to free space.

The variant that wastes more time: storage.delete.enabled was never set, so every deletion returned 405 Method Not Allowed and the tooling logged it at debug level. The UI still updated, because the UI was reading its own database. Now nothing was deleted and nothing was freed, and the two failures mask each other.

Check both before you conclude anything: did the deletes return 202, and has garbage collection actually run since?

Deleting a manifest

Deletion is by digest only. The specification is explicit: “a manifest can only be deleted by digest.” A successful delete returns 202 Accepted.

Read-only / Saferesolve a tag to its digest— The Docker-Content-Digest header is the value the delete endpoint requires. A HEAD costs nothing.

REGISTRY=registry.example.com
REPO=myorg/myapp
TAG=release-2026-06
ACCEPT='application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json'

DIGEST=$(curl -fsSI -H "Accept: $ACCEPT" \
"https://$REGISTRY/v2/$REPO/manifests/$TAG" \
| awk 'tolower($1) == "docker-content-digest:" {print $2}' | tr -d '\r')

echo "$TAG -> $DIGEST"

release-2026-06 -> sha256:0000000000000000000000000000000000000000000000000000000000000000

Illustrative output

Destructivedelete the manifest— Irreversible. Every deployment pinned to this digest loses its source. Verify nothing references it first.

REGISTRY=registry.example.com
REPO=myorg/myapp
DIGEST=sha256:REPLACE_ME

curl -fsS -X DELETE -o /dev/null -w '%{http_code}\n' \
"https://$REGISTRY/v2/$REPO/manifests/$DIGEST"

Illustrative output

A 405 here means storage.delete.enabled is off. A 404 means the digest was already gone. Only 202 means anything happened.

Untagged does not mean unused

The most dangerous assumption in registry retention is that an untagged manifest is dead. It is not, and this is precisely the population that --delete-untagged targets.

Every deployment that pins by digest — which is every deployment following the advice in this course — references a manifest without going through a tag. Retire the tag release-2026-06 and its manifest becomes untagged while twelve hosts are pinned to its digest. Those hosts keep running, because running containers do not consult the registry. The next new host, the next scale-out, and the next rollback all fail with a 404 on a digest that was valid yesterday.

Before deleting untagged manifests, collect the digests actually in use across the estate and exclude them. docker inspect --format '{{.Image}}' across the fleet is where that list comes from.

Distribution garbage collection

This is the step that frees disk, and it is the one with the sharp edge.

Read-only / Safedry run first, always— Mark and sweep with no deletion. The config path is positional and required; 3.x defaults to /etc/distribution/config.yml, 2.x used /etc/docker/registry/config.yml.

docker exec registry \
registry garbage-collect --dry-run /etc/distribution/config.yml

myorg/myapp
myorg/myapp: marking manifest sha256:0000...0000
myorg/myapp: marking blob sha256:1111...1111
myorg/myapp: marking blob sha256:2222...2222

12 blobs marked, 47 blobs and 0 manifests eligible for deletion
blob eligible for deletion: sha256:3333...3333
blob eligible for deletion: sha256:4444...4444

Illustrative output

The flags, from the upstream documentation:

Flag	Effect
`--dry-run`	Runs mark and sweep without deleting anything
`--delete-untagged`	Also removes manifests no tag currently references
`--quiet`	Suppresses output

The config file path is a positional argument, not a flag. Omitting it is the most common way this command fails to run at all.

Garbage collection against a writable registry can corrupt an image

This is the failure the brief for every registry runbook should open with. The upstream documentation states the requirement plainly — “You should ensure that the registry is in read-only mode or not running at all” — and the reason:

“If you were to upload an image while garbage collection is running, there is the risk that the image’s layers are mistakenly deleted leading to a corrupted image.”

Distribution garbage collection is stop-the-world mark-and-sweep. It builds the reachable set first, then deletes everything outside it. A push that uploads blobs after the mark phase has passed that repository puts those blobs outside the set, and the sweep removes them. The push then completes successfully and writes a manifest referencing layers that no longer exist.

The result is the nastiest kind of registry defect: a tag that exists, resolves, and returns a manifest, whose pull fails partway through with unknown blob or a 404 on a layer digest. The image looks present in every listing. It cannot be pulled by anyone, ever again, and the only repair is to rebuild and re-push.

The first diagnosis is usually “corrupted download” or “proxy problem”, because the failure is on a layer fetch rather than on the manifest, and it reproduces on every host — which people read as a network issue rather than as missing data.

The read-only window

Configuration changeenter maintenance read-only— Pushes are refused for the duration. Pulls continue to work, so a deploy of an existing image is unaffected.

storage:
delete:
  enabled: true
maintenance:
  readonly:
    enabled: true

The equivalent environment variable is REGISTRY_STORAGE_MAINTENANCE_READONLY_ENABLED=true, which is usually the easier lever for a containerised registry because it means restarting the container with one extra flag rather than templating a config file.

Announce the window. Pushes will fail; pulls will not. CI needs to know.
Record the current disk usage so you can state afterwards what the run actually reclaimed.
Collect the digests in use across the fleet if you intend to pass --delete-untagged.
Restart the registry with readonly enabled, and confirm a test push is refused.
**Run with --dry-run first** and read the eligible-for-deletion list. If a digest you care about appears there, stop.
Run for real.
Restart without readonly, and confirm a test push succeeds.
Pull one known image end to end — not a manifest HEAD, a full pull — to prove blobs are intact.

Step 8 is the one that catches a bad run, and it is the one everybody skips because the GC output said success. A manifest fetch will pass against a registry whose blobs were destroyed; only a pull that transfers layers proves otherwise.

Read-only / Safepost-GC integrity check— Forces a full layer transfer by removing the local copy first. Passing this is evidence; a manifest HEAD is not.

IMG=registry.example.com/myorg/myapp:release-2026-08

docker image rm "$IMG" 2>/dev/null || true
if docker pull "$IMG"; then
echo 'OK: manifest and all blobs present'
else
echo 'FAIL: registry is missing blobs for this image' >&2
fi

OK: manifest and all blobs present

Illustrative output

Mark, sweep, and the window between them

Garbage collection has two phases and the gap between them is the whole hazard.

Mark. The collector walks repositories/ and, for every manifest revision it finds, adds that manifest’s digest and every blob digest it references to an in-memory set. With --delete-untagged, manifests that no tag currently links to are excluded from the walk, so their blobs never enter the set.

Sweep. The collector walks blobs/ — the flat, content-addressed store — and deletes every blob whose digest is not in the set.

The set is built once. It is not updated while the sweep runs, and the registry has no lock preventing a client from pushing during either phase. Consider a push that starts after the mark phase has already walked its repository:

The client uploads layer blobs. They land in blobs/.
The sweep reaches them. They are not in the mark set — the mark phase finished before they existed.
They are deleted.
The client finishes the push and writes the manifest, which the registry accepts.

Now repositories/ names a manifest whose layer blobs are absent. A HEAD on the tag returns 200. A pull fails on the blob fetch.

There is no repair, because the data is gone: the blobs were the only copy. Read-only mode closes the window by refusing step 1.

Note also what GC does not do. It does not remove empty repository directories, it does not compact the filesystem, and on an object-store backend the deletions are individual API calls — a sweep over a large registry can take hours and cost real money in request charges.

Harbor: retention and GC are separate jobs

Harbor layers policy on top of the same underlying storage, and it keeps the same two-step separation — with one important difference worth knowing.

Tag retention rules are configured per project, in the UI or the API, not in harbor.yml. Each rule keeps artefacts matching one of five criteria:

retain the most recently pushed N artefacts
retain the most recently pulled N artefacts
retain artefacts pushed within the last N days
retain artefacts pulled within the last N days
retain always

Up to 15 rules per project. Rules can be scoped by repository and tag patterns, and Harbor offers a dry run so you can see what a rule would delete before it deletes it. Use it. The “most recently pulled” and “pulled within N days” criteria are the ones that behave most like an operator’s intent, because they track use rather than age.

Garbage collection is a separate operation, and Harbor is explicit about why: “When you delete images from Harbor, space is not automatically freed up. You must run garbage collection to free up space by removing blobs that are no longer referenced by a manifest from the file system.”

The difference from raw Distribution is worth naming, because it changes your maintenance planning: Harbor states that it “runs garbage collection without interrupting your ability to continue use Harbor, for example you are able to push, pull, or delete artifacts while garbage collection is running.” You do not need the read-only window that Distribution requires.

Do not generalise that to Distribution. They are different implementations of the same idea, and the raw registry’s documentation says the opposite.

What if garbage collection deletes a blob a deployment still needs?

Separate the two cases, because they have different symptoms and different fixes.

Case one: the manifest was deleted deliberately — a retention rule removed an untagged manifest that a host was pinned to by digest.

Symptom: manifest unknown on pull, for a digest that used to work. Existing containers are unaffected. New hosts and rollbacks fail.

Fix: re-push the image from any source that still has it — CI artefacts, another registry, a host that still holds the layers (docker save, then docker load and push elsewhere). Because content is addressed by hash, a re-push of identical bytes restores the same digest exactly, and every pinned reference starts working again. This is the one genuinely reassuring property in the whole area.

Prevention: collect in-use digests from the fleet and exclude them before running anything with --delete-untagged.

Case two: blobs were swept during a concurrent push.

Symptom: the manifest resolves fine but the pull fails on a layer. The error names a blob digest, not a manifest.

Fix: rebuild and re-push. If the build is reproducible you get the same digest back; if it is not, you get a new digest and every pin must be updated. This is worse than case one and it is why the read-only window is not optional.

Prevention: the read-only window.

In both cases, the check that would have caught it in minutes rather than at the next deploy is the post-GC full pull. Put it in the runbook.

A retention policy that survives contact

KEEP:
  - every digest currently running anywhere in the estate   (collected, not assumed)
  - the most recent 10 artefacts per repository
  - anything pulled in the last 90 days
  - anything tagged release-*                               (explicit, unbounded)

DELETE:
  - everything else, monthly

RECLAIM:
  - garbage collection, monthly, immediately after the retention pass,
    with the registry read-only for the duration

VERIFY:
  - a full docker pull of the current release, from a host with no
    local copy, after every GC run

Four lines of intent, one schedule, one assertion. The unbounded release-* rule is deliberate: an unbounded keep rule wastes disk, which is recoverable, and a too-aggressive delete rule destroys an artefact, which is not.

Why this matters

Registry retention is the rare maintenance task where the conservative failure and the aggressive failure are not symmetric. Keeping too much costs disk, and disk is cheap and the alert is loud. Deleting too much destroys the only copy of something, silently, and you find out during a rollback.

Layered on top of that is the mechanism problem: the operation that looks like cleanup frees nothing, and the operation that frees space will corrupt an image if you run it the obvious way. Both are documented, neither is intuitive, and the corrupted-image failure presents as a network problem.

Get three things right and the rest is scheduling: know which digests are actually in use before you delete, take the read-only window, and prove the result with a full pull rather than a status message.

Two operations, not one

Deleting a manifest

Distribution garbage collection

The read-only window

Harbor: retention and GC are separate jobs

A retention policy that survives contact

Knowledge check