What an image actually is: a config plus a stack of content-addressed layers, not a machine snapshot

What you actually pull

When you docker pull nginx:1.27, you do not download a machine. You download, in order: a small manifest (JSON, a few KB) that lists everything; a config blob (JSON) holding the environment variables, entrypoint, working directory, exposed ports, and the ordered list of layer digests that make up the root filesystem; and then the layers themselves — gzipped tarballs, each named by the sha256 of its contents. Inspect it directly:

$ docker manifest inspect nginx:1.27
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    { "platform": {"architecture":"amd64","os":"linux"}, "digest": "sha256:7f0a...", "size": 2295 },
    { "platform": {"architecture":"arm64","os":"linux"}, "digest": "sha256:e3c1...", "size": 2295 }
  ]
}

That top object is an index — one tag, several per-architecture manifests. The daemon picks the manifest matching your CPU, then pulls that manifest’s config and layers. For nginx:1.27 on amd64 that is 7 layers totalling ~67 MB compressed; the Debian base (~29 MB) and the nginx binaries dominate, and the per-tag application layer is often a few hundred KB.

The config is the image’s identity

Why does changing one environment variable produce a completely new image ID even when no file on disk changed? Because the image ID is not a hash of the layers — it is a hash of the config. The config blob is the part people forget exists. It is plain JSON:

{
  "architecture": "amd64", "os": "linux",
  "config": {
    "Env": ["PATH=/usr/local/sbin:/usr/local/bin:...", "NGINX_VERSION=1.27.0"],
    "Entrypoint": ["/docker-entrypoint.sh"],
    "Cmd": ["nginx", "-g", "daemon off;"],
    "ExposedPorts": {"80/tcp": {}}
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:1f3e... ",
      "sha256:8a2c... ",
      "sha256:b91d... "
    ]
  },
  "history": [ { "created_by": "RUN apt-get install ..." } ]
}

Two things matter here. First, rootfs.diff_ids is the ordered recipe for the filesystem: stack these layers, bottom to top, and you have the container’s root directory. Second, the sha256 of this config JSON itself is the image ID — the sha256:... you see in docker images --digests. Change one environment variable, rebuild, and the config bytes change, so the image ID changes, even if every layer digest is identical. The image is its config; the layers are shared content the config references.

What a container adds

An image is read-only — every layer is immutable, frozen by its digest. So how does a running container write a log file? When you docker run, the runtime stacks the image’s read-only layers via a union filesystem (overlay2 on Linux) and adds exactly one thin writable layer on top. Writes land there as copy-on-write: modify /etc/hosts and overlay2 copies the file up into the writable layer and edits the copy; the underlying read-only layer never changes. Delete the container and that writable layer is discarded — which is precisely why data you care about must live in a volume, not in the container. The image is the immutable stack; the container is that stack plus one disposable scribble layer.

This is also why “it’s a machine snapshot” misleads. A VM snapshot is a monolithic opaque disk image, copied whole. An OCI image is a structured, addressable, shared artifact: pull deltas (only layers you lack), share bases across hundreds of images, and rebuild deterministically from the config recipe.