Painless Docker - 2nd Edition

Where Docker and containerd Store Data on the Host

When you run a container, several things happen behind the scenes before your application actually starts.

First, containerd pulls an image.

An image is the packaged bundle that contains everything the container needs to run: a filesystem (files, directories, binaries) and metadata that describes how the container should start.

Once the image is downloaded, it's still not ready to run. At this point, the snapshotter comes into play.

The snapshotter is a component of containerd responsible for handling container filesystems. Its job is to manage how image layers are unpacked, stored on disk, combined together, mounted, and cleaned up over time.

In simple terms, the snapshotter turns an image into a real filesystem that a running container can use.

It does this by stacking the image layers on top of each other, then adding a small writable layer at the top. This writable layer is where the container can make changes, such as creating files or modifying configuration. The snapshotter then mounts this combined view as a filesystem. Only after this step can the container process actually start.

Later in this guide, this process is explained in more detail. For now, what matters is understanding the global picture: where Docker and containerd store all this data on the host system.

Where Docker and containerd store data on the host?

containerd stores its internal data under the directory:

/var/lib/containerd

This includes image data, filesystem snapshots, and runtime state.

Docker Engine, which sits on top of containerd, stores its own higher-level data under:

/var/lib/docker

This includes information about containers, volumes, networks, and build artifacts.

Although Docker uses containerd internally, these two directories serve different purposes.

Main containerd directories:

• /var/lib/containerd/io.containerd.content.v1.content/
  This directory stores the raw content blobs used by images and containers. These blobs include image layers, image configuration files, and image manifests (in OCI and Docker formats). Think of this as the place where the actual bytes of images live.

• /var/lib/containerd/io.containerd.metadata.v1.bolt/
  containerd uses a database called BoltDB to store metadata about images, containers, and snapshots. This database acts as an index that connects content blobs together. Without it, containerd would have files on disk, but no structured way to understand how they relate.

• /var/lib/containerd/io.containerd.snapshotter.v1.overlayfs/,
  /var/lib/containerd/io.containerd.snapshotter.v1.btrfs/, and others
  These directories are used by different snapshotters. Each snapshotter implements a specific strategy for storing and mounting container filesystems. For example, the overlayfs snapshotter relies on the Linux OverlayFS filesystem. Only one snapshotter is usually active at a time, but multiple directories may exist.

• /var/lib/containerd/io.containerd.sandbox.controller.v1.shim/