Docker Registry Operations, Garbage Collection, Retention, Search, Proxying, and Production Troubleshooting: Concepts, Architecture, and Mental Model

1. The operator’s problem: “image size” and “tag count” are misleading

Chapter 8 taught Docker/OCI repository basics. At production scale, the difficult questions are different: Which exact manifest did a tag resolve to? Which layers are shared by ten images? Why did deleting a tag free almost no disk space? Why does a proxy return an older tag than expected? Why does the Docker client report 401, 404, or 429? Which task can safely reclaim unreferenced layers, and which task merely marks repository content as deleted?

The operational mistake is to treat a Docker image as one file. A registry stores a graph of metadata and blobs. Retention and troubleshooting have to follow that graph.

2. Identity hierarchy: reference → tag or digest → manifest → config/layers

flowchart LR
  REF[image reference] --> TAG[tag such as 1.4 or latest]
  REF --> DG[digest reference sha256:...]
  TAG --> MAN[manifest or image index]
  DG --> MAN
  MAN --> CFG[config blob]
  MAN --> L1[layer A]
  MAN --> L2[layer B]
  OTHER[another manifest] --> L1
  OTHER --> L3[layer C]

A tag is a human-friendly alias. It can be moved to point to a different manifest unless your process prevents that. A digest is calculated from manifest content and identifies those manifest bytes. A manifest references a configuration blob and one or more layer blobs. Multiple manifests can reuse the same layer digest, so physical storage is deduplicated within the relevant blob-store scope.

A multi-architecture tag may point to a manifest list or OCI image index, which in turn points to platform-specific manifests. That means “delete the tag” may affect only one top-level reference while many referenced blobs remain live through another manifest.

3. How Nexus represents Docker content

Current Sonatype documentation defines a Docker component as a tagged manifest. A tag is an alias that points to a manifest; a layer is a binary blob referenced by one or more manifests. Tags and layers do not each become independent “components” in the usage-count sense, even though tags, manifests, and layers are all persisted as assets/state inside Nexus.

4. Hosted, proxy, and group remain different operating roles

• Hosted: authoritative destination for internal pushes. Retention directly changes organization-owned registry content.
• Proxy: cache/mediation boundary for an upstream registry. Deleting cached content is not the same as deleting upstream content; the next allowed request may fetch it again.
• Group: read aggregation over members. The group does not make member lifecycle state identical, and member order can influence which image reference wins.

Do not troubleshoot a proxy staleness problem by deleting content from a hosted member, and do not assume clearing a Docker client cache invalidates the Nexus proxy cache.

5. Docker cleanup is a chain, not one “garbage collect” button

flowchart LR
  SLA[retention intent] --> POLICY[cleanup policy or supported targeted deletion]
  POLICY --> TAGS[old tagged components logically removed]
  TAGS --> GC[Docker - Delete unused manifests and images]
  GC --> ORPHAN[unreferenced manifests/layers soft-deleted]
  ORPHAN --> COMPACT[Admin - Compact blob store]
  COMPACT --> SPACE[physical space reclaimed]

Current Sonatype guidance describes a Docker-specific sequence. Cleanup policies remove old Docker components/tags according to criteria. That can leave manifests and layers with no remaining tag reference. The Docker - Delete unused manifests and images task then identifies and removes unreferenced Docker data. Finally, the blob-store compaction/reclamation step permanently removes soft-deleted blob content and returns physical capacity for file-backed storage.

6. Why deleting a 700 MB “image” may free 4 KB—or nothing yet

Suppose service-a:1.0 and service-b:1.0 share a 650 MB base layer. Removing service-a:1.0 may only remove the tag/manifest relationship. The 650 MB layer remains referenced by service-b:1.0. Even when no manifest references it, Nexus may still retain the soft-deleted blob until the appropriate garbage-collection and compaction stages run.

Therefore, three numbers must be separated: logical components/tags, unreferenced Docker assets, and physical blob-store bytes. A capacity dashboard that conflates them creates false incident reports.

7. Search and discovery have several different scopes

Nexus UI/Search API searches content already known to Nexus: hosted images plus content previously proxied/cached. Current Nexus search is SQL-backed and exposes Docker-specific fields such as image name, image tag, and layer ID. The Docker Registry API can list tags for a known repository name, subject to implementation limits. The Docker CLI's docker search is not a universal registry catalog client; Sonatype documents it primarily around Docker Hub/group behavior and older V1 search support.

8. A Docker pull is many HTTP requests

A single docker pull normally causes a sequence such as /v2/ capability/authentication checks, bearer-token exchange, manifest HEAD/GET, config download, and multiple blob GETs. Nexus metrics therefore count far more HTTP requests than “number of image pulls.”

Client → GET /v2/
Registry → 401 + WWW-Authenticate: Bearer ...
Client → token request
Client → HEAD/GET /v2/learner-example/demo/manifests/1.0
Client → GET /v2/learner-example/demo/blobs/sha256:...
Client → GET /v2/learner-example/demo/blobs/sha256:...

A 401 may be a normal authentication challenge, not necessarily a failure. The final client outcome, token realm, privileges, and request path matter.

9. Authentication is a protocol boundary

Self-hosted Docker access requires the Docker Bearer Token Realm for Docker clients. Repository-view privileges still determine what the user can read/write. A browser session or SAML/OIDC login does not automatically make a Docker daemon authenticated. Keep noninteractive client credentials scoped and out of image references, shell history, and screenshots.

10. Proxy freshness, remote health, and rate limits are separate mechanisms

A Docker proxy can serve cached manifests/layers when appropriate, fetch remote metadata when stale, and be affected by upstream authentication/rate limits. A 429 Too Many Requests may originate upstream or from another protective layer. A stale tag can be caused by Nexus proxy metadata/cache behavior, a Docker client cache, an upstream registry that moved the tag, or a reverse proxy/CDN in front of Nexus.

Diagnosis should record the exact image reference, resolved digest, repository member, Nexus cache state, remote response, and client cache state before invalidating anything.

11. Path-based routing is the preferred modern Nexus model

Current Sonatype Docker documentation recommends path-based routing for modern deployments. A client reference looks like:

nexus.example.invalid/docker-group/learner-example/demo:1.0

The repository name is part of the registry path, without the usual /repository/ prefix used by generic HTTP access. Port connectors are legacy and consume server resources; Sonatype recommends limiting them. Subdomain routing is Pro-only. Do not mix routing methods casually during migration.

12. Docker repository format versus native OCI repository format

Do not collapse these terms. Docker repositories support container-image workflows and OCI image-spec compatibility. Starting in the 3.94 line, Nexus also offers a native OCI repository format (Community and Pro self-hosted) for images and broader OCI artifacts such as SBOMs, signatures, attestations, and Helm content through OCI-compatible tools. Chapter 24 focuses on Docker registry operations; use native OCI repositories deliberately when your artifact model requires them.

13. Read-only inspection before mutation

On a disposable instance, collect the following before touching retention:

# Nexus REST inspection; inject a disposable scoped credential at runtime.
curl -fsS "$NEXUS_URL/service/rest/v1/status"
curl -fsS "$NEXUS_URL/service/rest/v1/repositories"
curl -fsS "$NEXUS_URL/service/rest/v1/search?repository=ch24-docker-hosted&format=docker"

# Registry endpoint inspection through the configured Docker route.
curl -i "$REGISTRY/v2/"
curl -fsS "$REGISTRY/v2/learner-example/ch24-demo/tags/list"

Depending on your authentication configuration, the Registry request may intentionally return 401 plus WWW-Authenticate. Preserve that header; it is useful evidence. Never paste a bearer token into lesson notes.

14. State map for troubleshooting

15. Knowledge check

16. Summary and next step

Docker registry operations are graph operations. Tags point to manifests; manifests reference configs/layers; layers may be shared; proxy state and client caches are different; and cleanup proceeds through logical selection/deletion, Docker-specific orphan cleanup, and later physical reclamation. Lesson 2 turns that model into a disposable workflow and captures before/after evidence rather than trusting disk usage alone.

Official references and version notes

• Sonatype: Docker Registry — Docker repository routing, Registry API support, manifest lists, OCI image support, and current path-based routing guidance.
• Sonatype: Repository Manager Concepts — Docker component/tag/manifest/layer relationships and storage implications.
• Sonatype: Cleanup Policies — Docker cleanup sequence, policy criteria, soft deletion, Docker GC interaction, and blob-store compaction.
• Sonatype: Tasks — current Docker GC, incomplete-upload cleanup, repository cleanup, and compact blob-store task behavior.
• Sonatype: Searching Docker — Docker client search constraints and Nexus repository/group behavior.
• Sonatype: Searching for Components — current SQL-backed Nexus search and Docker-specific image/tag/layer criteria.
• Sonatype: Search API — supported paginated search endpoints and format-specific fields.
• Sonatype: Docker Authentication — Docker Bearer Token Realm and client authentication flow.
• Sonatype: Proxy Repository for Docker — Docker Hub/private ECR proxy behavior and current upstream-authentication options.
• Sonatype: Nexus Repository 3.95.0–3.95.2 Release Notes — dated release line and open Docker HEAD/lastDownloaded cleanup issue.
• Sonatype: Nexus Repository 3.91.x Release Notes — Docker manifest/tag integrity and garbage-collection correctness fixes relevant to modern behavior.
• Sonatype: OCI Repositories — native OCI hosted/proxy/group support introduced in the 3.94 line; separate it from the older Docker repository format.
• Sonatype nexus-public 3.95.2-01 release — dated patch baseline used in this chapter.