Hello 👋

I just published a new tutorial:

​How Container Images Actually Work: Layers, Configs, Manifests, Indexes, and More​

Docker made container images look deceptively simple from the outside: you docker build, docker push, and docker run, and everything just works. But under the hood, the image format is an intricate graph of content-addressed objects, and, as with any abstraction, implementation details leak.

The moment you start doing anything slightly more advanced - multi-platform builds, registry-to-registry copies, provenance attestation, digest pinning, or image comparison - things can get confusing pretty quickly.

• Why does the same image tag pull different content on different machines?
• Why can the "same" image get a different digest after being copied to another registry?
• What exactly is the difference between an image ID and an image digest?
• What even is a multi-platform image - one image or many? And if the latter, how can it still be represented by just one reference?

The key idea is that a container image is not one monolithic blob. It's a graph of content-addressed objects, where different pieces solve different problems:

• Describing the runtime config
• Representing the filesystem
• Distributing the image through registries
• Grouping multiple platform-specific variants under one tag

Once you understand the internal image structure, a lot of image-related "weirdness" will suddenly make much more sense. But to see it, reading the OCI specs may not be enough. A less dry, more practical approach is needed, and this write-up is my attempt to find an explanatory angle that actually works.

Traditionally, the tutorial includes a good deal of diagrams, CLI examples, and a few hands-on exercises to make the concepts concrete and tangible. Check it out!​

Happy building!

Ivan