Graphdrivers

Purpose

The graphdriver layer is the legacy implementation of image and container filesystem layers. It applies tarballs as content-addressable diffs and stacks them with a union filesystem. It is being replaced by containerd snapshotters, but is still active when the daemon runs with the legacy image store.

Layout

daemon/graphdriver/
├── driver.go         # Driver interface, registry
├── register/         # Per-driver init imports
├── overlay2/         # OverlayFS-based driver (Linux default)
├── btrfs/            # btrfs subvolumes (Linux)
├── zfs/              # ZFS datasets (Linux/FreeBSD)
├── vfs/              # No CoW; literal file copies. Used in tests.
├── fuse-overlayfs/   # FUSE OverlayFS (rootless mode)
├── windows/          # Windows graph driver via HCS
├── overlayutils/     # OverlayFS helpers
└── copy/             # Copy-with-progress helpers

Driver interface

Driver is declared in driver.go. Each driver provides:

• Create(id, parent, opts) and CreateReadWrite(id, parent, opts) to allocate a layer.
• Get(id, mountLabel) -> filesystem path to mount the layer.
• Put(id) to unmount.
• Diff(id, parent) to produce a tarball of the changes.
• ApplyDiff(id, parent, tar) to materialize a tarball as a layer.
• Remove(id) to drop a layer.
• Status and GetMetadata for docker info.

The driver ID id is a chain ID — a hash of the layer's content plus all its parents.

Driver selection

daemon/graphdriver/driver_linux.go (and friends) defines a priority list. By default the daemon prefers overlay2 on Linux, windowsfilter on Windows, and falls back through the list when the preferred driver isn't usable. The priority can be overridden via --storage-driver or DOCKER_LDFLAGS at build time.

overlay2

overlay2/ is the dominant driver. Each layer is a directory with lower, upper, merged, and work subdirs; mounts are plain mount -t overlay. Layer chain depth is bounded by the kernel (typically ~125 layers). The driver also supports project quotas via internal/quota/ (XFS) and the nfs_export=on overlay option for NFS-backed lower.

fuse-overlayfs

Used in rootless mode where the kernel won't allow unprivileged overlay mounts. Wraps the userland fuse-overlayfs binary.

vfs

The "no copy-on-write" driver. It literally copies layer contents on every fork. It exists for compatibility on filesystems where no CoW driver works, and for deterministic test fixtures.

btrfs / zfs

Use native filesystem snapshots. Faster than vfs but require dedicated filesystems.

windows

The Windows graph driver delegates to the Host Compute Service (HCS). It works in conjunction with the Windows-specific layer code in daemon/internal/image/ and daemon/internal/layer/.

graphtest

graphtest/ provides a shared test suite that every graphdriver runs to ensure conformance.

When this is active

The daemon picks between containerd snapshotters and graphdrivers in daemon/image_store_choice.go. Graphdrivers are only initialized if the legacy store is selected. Otherwise daemon/snapshotter/ handles the equivalent role on top of containerd.

Entry points for modification

• New driver: implement Driver, add an import in register/, gate by build tag for OS-specific drivers.
• Quota/policy: see internal/quota/.
• Tests: extend graphtest/ to cover any new behavior.

See also

• Image management for the higher-level picker between containerd and legacy.
• daemon/snapshotter/ for the modern equivalent.