Image anatomy: index, manifest, config and layers

What an image is on the wire and on disk.

Docker in depth assumes you know Docker fundamentals. You can run and inspect containers, write a Dockerfile, use volumes, networks and Compose, and push to a registry. Every command runs on the main lab VM, secopslog-docker. You build it from the lab kit as described in "Installing Docker Engine and running your first container" in Docker for beginners (./setup/create-lab.sh, then multipass shell secopslog-docker). A few lessons change the daemon or the host, so they use the second VM, secopslog-docker-sec. They say so in their first lines. They also give the commands to create that VM (./setup/create-lab.sh --profile sec) and open a shell in it (multipass shell secopslog-docker-sec). If you want a clean start, reset the main VM between lessons with /opt/secopslog-lab/setup/reset-lab.sh.

Run docker pull without -q and the output ends with a Digest: line. That digest isn't the hash of a file inside the image. It isn't the image ID of the old Docker either. It names a small JSON document, and everything else about the image hangs off that document by more digests. You'll walk that chain once, from the tag to the bytes. First you'll do it on alpine:3.24 from Docker Hub, then on an image you build and push to a registry of your own. The lesson files (a Dockerfile and a two-line script) go in ~/lab/imglayers.

A tag points at an index

docker buildx imagetools inspect reads an image straight from its registry without pulling it. With --raw it prints the exact JSON the registry serves. Save it to a file so the next commands can work on the same copy:

mediaType says this is an OCI image index. That's a list of manifests, each with a digest, a size and a platform. The first entry is the image for linux/amd64. The second has platform unknown/unknown and the annotation vnd.docker.reference.type: attestation-manifest. You don't run it. It's a record about the image named in vnd.docker.reference.digest, here the amd64 manifest. Here's the whole index, one line per entry:

There are eight platforms, each followed by its attestation manifest. When docker pull runs on this arm64 VM, it reads the index, picks the linux/arm64/v8 entry and downloads only that. The local store keeps the index and remembers the platforms it skipped:

Only linux/arm64/v8 has content. The other rows are known but cost nothing. On an amd64 machine the linux/amd64 row carries the data instead. The second command shows what Docker 29 means by an image ID. With the containerd image store (the default on fresh 29 installs), the ID is the digest of the index. It's the same digest the registry serves for the tag. .Descriptor says so plainly: media type index, that digest, and its size in bytes. Older hosts on the legacy graph-driver store use the digest of the config instead. "Inspecting, exporting and cleaning up images" shows both.

The manifest: one config, a list of layers

Now follow the entry for this machine's architecture. The command asks the daemon for its CPU architecture, so the same lines work on arm64 and amd64:

Besides schemaVersion, mediaType and optional annotations, an image manifest points at two kinds of content. config points at one JSON blob. It holds the runtime defaults (command, environment, user, working directory), the build history and the list of layer IDs. layers lists the filesystem layers in order, bottom first. Each one's a gzip-compressed tar archive with its digest and compressed size. alpine has a single layer of about 4 MB. Every arrow in this chain is a digest. The tag resolves to the index digest, the index lists manifest digests, and the manifest lists config and layer digests. Change one byte of a layer and its digest changes. Then the manifest changes, and so does the index. That's why a digest at the top pins everything below it.

Build an image and read it back

Next comes an image whose contents you know. The Dockerfile mixes instructions that change files with instructions that only change metadata:

FROM alpine:3.24
WORKDIR /app
RUN adduser -D -H -u 10001 app
COPY --chmod=0755 greet.sh /app/greet.sh
ENV GREETING=hello
LABEL org.opencontainers.image.title="lab-anatomy"
USER app
CMD ["/app/greet.sh"]

#!/bin/sh
echo "$GREETING from $(id -un) on $(uname -m)"

The steps before the export are cut here (they ran on this first build and read CACHED on a rebuild). The export lines at the end are the chain from the previous section, produced locally. You'll see the image manifest, its config, an attestation manifest, and the manifest list (another name for an index) that ties them together. The last digest is the image ID. Even a single-platform build produces an index on Docker 29, because BuildKit attaches a minimal provenance attestation by default. The image runs as expected:

Compare the history with the layers:

History has nine rows: two from alpine's own build and seven from this Dockerfile. The image has four layers. First comes alpine's, then WORKDIR (it had to create /app). Then RUN adduser (it changed /etc/passwd, /etc/group and /etc/shadow) and COPY. ENV, LABEL, USER and CMD show 0B because they changed only the config. They add history entries and no layer at all, not even an empty one. <missing> in the IMAGE column only means that no separate image exists for that step. That's normal for anything built with BuildKit or pulled. Which of these steps reruns on the next build depends on the cache rules in "Layers and the build cache" in Docker for beginners.

Note what .RootFS.Layers lists. These aren't the layer digests from a manifest. They're diff IDs, the digests of the uncompressed tar streams. The next section shows you the difference with a real push.

What a registry stores

Start a registry:3 container on a lab network, published on the VM's loopback address only, and push the image to it:

Each line is one blob. You'll count the four layers, the provenance document and the two-byte empty config of the attestation manifest. The image config and the manifests go up after them without a progress line. The digest the push prints is the index digest, the same value as the local image ID. Now read back what the registry holds: the index, then the image manifest it points to:

The first layer's digest is identical to the single layer of alpine's arm64 manifest above. Same bytes, same digest. So a registry stores it once, and a host that already has alpine never downloads it again. That sharing is the whole reason layers exist as separate blobs. The config, read through --format '{{json .Image}}', shows the runtime defaults. It also shows the history, with empty_layer marking the metadata-only steps:

Finally, prove the content addressing yourself. Fetch the config and the top layer straight from the registry's HTTP API and hash them:

The config blob hashes to its digest. The layer blob hashes to the digest in the manifest. The same layer, decompressed, hashes to the last entry of diff_ids. Registries and manifests deal in compressed blobs. The config and the unpacked snapshots on a host deal in uncompressed content. Recompress the same layer with different settings and it gets a new blob digest in the manifest, but it keeps its diff ID. That's why you can't compare a manifest's layer digests with docker image inspect output and expect a match.

The attestation manifest

The second entry of your pushed index is the provenance BuildKit attached:

It's an ordinary OCI manifest with an artifactType that marks it as an attestation. It has an empty config and one layer of media type application/vnd.in-toto+json. That layer's annotation names the predicate: SLSA provenance v1, a description of how the image was built. subject points back at the image manifest it describes. Tools that don't understand attestations skip the unknown/unknown entry, which is why docker pull and docker run ignore it. Two things follow for you in practice. Your own single-platform images are indexes once pushed, so the digest to record and deploy is the index digest. And when you copy an image between repositories, the attestations should come along. Promoting the index digest does that ("Tags, digests and promotion"). "Pinning, SBOMs, provenance and scanning" in Advanced container security covers what the provenance contains, the SBOM attestation, and how to verify both.

Some topics belong to other lessons. A running container adds a writable layer on top of these read-only ones ("Images, containers and the core commands" in Docker for beginners). Where the content store and snapshots live on disk is the subject of "Where Docker keeps data". Deleting a file in a later layer hides it, but its bytes stay in the earlier layer. "Slimming images and layer hygiene" in Advanced container security shows how that leaks data. Remove what you created:

Try this

Before you run the cleanup, add one more ENV line and one more RUN line that writes a file to the Dockerfile in ~/lab/imglayers, and rebuild. Predict how many rows docker history will show and how many entries .RootFS.Layers will list, then check both against the nine rows and four layers above. Only the RUN line should cost you a layer.

Takeaway

Record and deploy the index digest that docker push prints, since it pins every manifest, config and layer below it. Where this goes wrong is comparing digests across the wrong level: the layer digest in a manifest is a compressed blob, while .RootFS.Layers holds uncompressed diff IDs, so the two never match. A script that checks one against the other will report every image as tampered with.

Related