2.2.1.2 Containerd Image Transfer

Containerd image transfer is containerd's responsibility for pulling image layers from a registry and pushing them back, handling the underlying content-addressable storage model that lets identical layers be shared across multiple images without duplication.

Pulling Layers From a Registry

When an image is pulled, containerd checks which of its layers already exist in local storage and downloads only the layers that are missing, identifying each layer by a content hash rather than by name alone.

ctr images pull docker.io/library/nginx:latest

If another image sharing some of the same base layers has already been pulled, those shared layers are reused rather than downloaded again.

Content-Addressable Storage

Each image layer is identified by a cryptographic digest of its content, which means two images that happen to share an identical layer — for example, both based on the same version of debian:bookworm-slim — refer to and store that layer only once.

ctr content ls

This lists the content blobs containerd has stored, identified by their digests rather than by which image they originally belonged to.

Verifying Layer Integrity

Because layers are identified by their content hash, containerd can verify that a downloaded layer matches exactly what was expected, detecting corruption or tampering during transfer.

ctr images check

Pushing Images Back to a Registry

The reverse operation, pushing, uploads any layers a registry does not already have, again avoiding redundant transfer of layers the registry already possesses.

ctr images push registry.example.com/myapp:1.0

Why Content-Addressable Transfer Matters

This model is what makes image distribution efficient at scale: a registry storing many different application images that share common base layers does not need to store or transfer those shared layers redundantly, and a host that already has a given layer locally — because some other image used it — never needs to download it again.

docker pull myapp:2.0

Pulling a new version of an image that only changed its top application layer is fast precisely because every shared lower layer is already present locally, a direct consequence of this content-addressable transfer mechanism.