The container registry API is the part of Docker and Kubernetes that most teams only meet when something breaks. Ivan Velichko’s iximiuz Labs tutorial is useful because it strips the registry down to HTTP calls: upload blobs, attach a manifest, pull by digest, list tags, and see what deletion really means.
Table of Contents
The short version
- A registry is closer to a content-addressed blob store than a simple tag database.
docker pushuploads layer and config blobs first, then publishes a JSON manifest that points at them.docker pullstarts with the manifest, so many pull failures are easier to debug if you inspect that document before blaming the runtime.- Deleting a tag is not the same as deleting every blob behind the image.
- Multi-platform images add an image index above per-platform manifests, which is where amd64 versus arm64 confusion often starts.
What happened
iximiuz Labs published a hands-on tutorial called “How Container Registries Work: Pushing and Pulling Images By Hand.” It walks through the OCI-style registry flow with curl, not Docker. The tutorial starts with raw blob upload and download, then builds toward pushing an image manifest, listing tags, pulling image contents, deleting image data, and storing multi-platform images.
The point is not that everyone should replace Docker with shell scripts. The point is that the registry has a small, inspectable HTTP surface. A blob upload starts with POST /v2/<repo>/blobs/uploads/, finishes with a digest-aware PUT, and a tag appears when a manifest is pushed to PUT /v2/<repo>/manifests/<tag>. Once you see that flow, tags stop feeling like magic labels and start looking like pointers to JSON documents.
Why this is worth watching
The registry gives platform teams a better failure model. If a cluster pulls the wrong image, the useful question is not “why is Docker weird?” It is which manifest the tag currently resolves to, which config and layer digests that manifest references, and whether the client selected the right platform entry.
That matters in boring, expensive ways. A CI pipeline can push successfully while production still resolves an older digest. A cleanup job can remove a tag while shared layer blobs remain. An Apple Silicon laptop can produce an image that works locally but misses the manifest entry a mixed Kubernetes fleet expects. These are not exotic edge cases. They are the kind of problems that show up after a release, when people are looking at dashboards instead of registry headers.
The tutorial also hints at a broader registry shift without over-selling it. OCI registries now hold more than runnable images: Helm charts, SBOMs, provenance attestations, and other artifacts can use the same distribution model. For more infrastructure briefs, the IT & AI archive tracks similar developer-tool shifts as they move from novelty into operational plumbing.
What the container registry API shows
The container registry API shows that image delivery is mostly a chain of small claims: this tag points to this manifest, this manifest points to these digests, and these digests are the bytes the runtime needs. Once that chain is visible, debugging gets less mystical.
What the discussion is missing
There does not appear to be a public Hacker News thread for this specific tutorial. That is a shame, because the useful debate would probably be practical rather than philosophical.
The missing discussion is about where teams should draw the line. Most engineers do not need to hand-push manifests every week. But build, SRE, security, and platform teams benefit from knowing enough of the container registry API to answer three questions during an incident: what does this tag point to, which blobs does this manifest need, and did the client choose the platform variant we expected?
The other open question is tooling. crane, regctl, oras, and registry vendor CLIs already wrap much of this work. The best use of the tutorial is not memorizing every endpoint. It is learning the mental model behind those tools so their output makes sense under pressure.
The practical read
If you ship containers, run through the tutorial once with a throwaway registry. Then add a few registry-level checks to your normal debugging playbook.
Start by resolving tags to digests before and after a deploy. Inspect the manifest media type when a pull fails on one architecture but not another. Treat deletion as a manifest-and-garbage-collection problem, not a tag-removal problem. For security work, check whether the artifacts you care about, such as SBOMs or attestations, are attached in a way your scanners and deployment systems can actually find.
That is the practical value of the container registry API. It turns image distribution from a black box into a set of documents and blobs you can inspect.