engine: containerd default storage backend

dvdksn · dvdksn · commit 588a76f306d6 · 2025-11-13T14:13:44.000+01:00
Signed-off-by: David Karlsson &lt;35727626+dvdksn@users.noreply.github.com&gt;
diff --git a/content/manuals/engine/daemon/_index.md b/content/manuals/engine/daemon/_index.md
@@ -98,24 +98,34 @@ The Docker daemon persists all data in a single directory. This tracks
 everything related to Docker, including containers, images, volumes, service
 definition, and secrets.
 
-By default this directory is:
+By default the daemon stores data in:
 
-- `/var/lib/docker` on Linux.
-- `C:\ProgramData\docker` on Windows.
+- `/var/lib/docker` on Linux
+- `C:\ProgramData\docker` on Windows
 
-You can configure the Docker daemon to use a different directory, using the
-`data-root` configuration option. For example:
+When using the [containerd image store](/manuals/engine/storage/containerd.md)
+(the default for Docker Engine 29.0 and later on fresh installations), image
+and container snapshots are stored in `/var/lib/containerd`. Other daemon data
+(volumes, configs, secrets) remains in `/var/lib/docker`.
+
+When using [classic storage drivers](/manuals/engine/storage/drivers/_index.md)
+like `overlay2` (the default for upgraded installations), all data is stored in
+`/var/lib/docker`.
+
+### Configure the data directory location
+
+You can configure the Docker daemon to use a different directory using the
+`data-root` configuration option:
 
 ```json
 {
   "data-root": "/mnt/docker-data"
 }
 ```
 
-Since the state of a Docker daemon is kept on this directory, make sure you use
-a dedicated directory for each daemon. If two daemons share the same directory,
-for example, an NFS share, you are going to experience errors that are difficult
-to troubleshoot.
+Make sure you use a dedicated directory for each daemon. If two daemons share
+the same directory, for example an NFS share, you will experience errors that
+are difficult to troubleshoot.
 
 ## Next steps
 
diff --git a/content/manuals/engine/storage/_index.md b/content/manuals/engine/storage/_index.md
@@ -8,6 +8,22 @@ aliases:
   - /storage/
 ---
 
+Docker storage covers two different concepts:
+
+**Container data persistence** (this page): How to store application data
+outside containers using volumes, bind mounts, and tmpfs mounts. This data
+persists independently of container lifecycle.
+
+**Daemon storage backends** ([containerd image store](containerd.md) and
+[storage drivers](drivers/)): How the daemon stores image layers and container
+writable layers on disk.
+
+This page focuses on container data persistence. For information about how
+Docker stores images and container layers, see
+[containerd image store](containerd.md) or [Storage drivers](drivers/).
+
+## Container layer basics
+
 By default all files created inside a container are stored on a writable
 container layer that sits on top of the read-only, immutable image layers.
 
@@ -78,9 +94,15 @@ Docker Engine API using a named pipe.
 
 ## Next steps
 
+For more details on persistent data storage for containers:
+
 - Learn more about [volumes](./volumes.md).
 - Learn more about [bind mounts](./bind-mounts.md).
 - Learn more about [tmpfs mounts](./tmpfs.md).
-- Learn more about [storage drivers](/engine/storage/drivers/), which
-  are not related to bind mounts or volumes, but allow you to store data in a
-  container's writable layer.
+
+If you want to explore how the Docker daemon stores data:
+
+- Learn about the [containerd image store](containerd.md), the default storage
+  backend for Docker Engine 29.0 and later.
+- Learn about [storage drivers](drivers/), the legacy approach to storing image
+  layers and container writable layers.
diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md
@@ -2,55 +2,154 @@
 title: containerd image store with Docker Engine
 linkTitle: containerd image store
 weight: 50
-keywords: containerd, snapshotters, image store, docker engine
-description: Learn how to enable the containerd image store on Docker Engine
+keywords: containerd, snapshotters, image store, docker engine, migration
+description: Learn about the containerd image store and how to migrate to it
 aliases:
   - /storage/containerd/
 ---
 
-{{< summary-bar feature_name="containerd" >}}
+The containerd image store is the default storage backend for Docker Engine
+29.0 and later on fresh installations. If you upgraded from an earlier version,
+your daemon continues using the legacy graph drivers (overlay2) until you
+migrate.
 
 containerd, the industry-standard container runtime, uses snapshotters instead
-of the classic storage drivers for storing image and container data.
-While the `overlay2` driver still remains the default driver for Docker Engine,
-you can opt in to using containerd snapshotters as an experimental feature.
+of classic storage drivers for storing image and container data.
 
-To learn more about the containerd image store and its benefits, refer to
-[containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md).
+> [!NOTE]
+> The containerd image store is not available when using user namespace
+> remapping (`userns-remap`). See
+> [moby#47377](https://github.com/moby/moby/issues/47377) for details.
+
+## Why use the containerd image store
+
+The containerd image store uses snapshotters to manage how image layers are
+stored and accessed on the filesystem. This differs from the classic graph
+drivers like overlay2.
+
+The containerd image store enables:
+
+- Building and storing multi-platform images locally. With classic storage
+  drivers, you need external builders for multi-platform images.
+- Working with images that include attestations (provenance, SBOM). These use
+  image indices that the classic store doesn't support.
+- Running Wasm containers. The containerd image store supports WebAssembly
+  workloads.
+- Using advanced snapshotters. containerd supports pluggable snapshotters that
+  provide features like lazy-pulling of images (stargz) or peer-to-peer image
+  distribution (nydus, dragonfly).
+
+For most users, the migration is transparent. The storage backend changes, but
+your workflows remain the same.
 
 ## Enable containerd image store on Docker Engine
 
-Switching to containerd snapshotters causes you to temporarily lose images and
-containers created using the classic storage drivers.
-Those resources still exist on your filesystem, and you can retrieve them by
-turning off the containerd snapshotters feature.
+If you're upgrading from an earlier Docker Engine version, you need to manually
+enable the containerd image store.
+
+> [!IMPORTANT]
+> Switching storage backends temporarily hides images and containers created
+> with the other backend. Your data remains on disk. To access the old images
+> again, switch back to your previous storage configuration.
+
+Add the following configuration to your `/etc/docker/daemon.json` file:
+
+```json
+{
+  "features": {
+    "containerd-snapshotter": true
+  }
+}
+```
+
+Save the file and restart the daemon:
+
+```console
+$ sudo systemctl restart docker
+```
+
+After restarting the daemon, verify you're using the containerd image store:
+
+```console
+$ docker info -f '{{ .DriverStatus }}'
+[[driver-type io.containerd.snapshotter.v1]]
+```
+
+Docker Engine uses the `overlayfs` containerd snapshotter by default.
+
+## Migrate from overlay2 to containerd image store
 
-The following steps explain how to enable the containerd snapshotters feature.
+Docker Engine provides an automatic migration feature to help you switch from
+the legacy overlay2 driver to the containerd image store.
 
-1. Add the following configuration to your `/etc/docker/daemon.json`
-   configuration file:
+### Basic migration
+
+To migrate automatically when you remove all images and containers:
+
+1. Add the migration feature to your `/etc/docker/daemon.json`:
 
    ```json
    {
      "features": {
-       "containerd-snapshotter": true
+       "containerd-migration": true
      }
    }
    ```
 
-2. Save the file.
-3. Restart the daemon for the changes to take effect.
+2. Remove all images and containers:
+
+   ```console
+   $ docker rm -f $(docker ps -aq)
+   $ docker rmi -f $(docker images -q)
+   ```
+
+3. Restart the daemon:
 
    ```console
    $ sudo systemctl restart docker
    ```
 
-After restarting the daemon, running `docker info` shows that you're using
-containerd snapshotter storage drivers.
+After restart, the daemon uses the containerd image store. Your old overlay2
+data remains on disk but is hidden. If you switch back to overlay2, that data
+becomes accessible again.
+
+### Threshold-based migration
+
+For daemons with existing images, you can set a size threshold for automatic
+migration. If your graph driver content doesn't exceed the threshold, the
+daemon migrates automatically on restart.
+
+Set the `DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD` environment variable in your
+daemon's environment. For systemd, use `systemctl edit`:
 
 ```console
-$ docker info -f '{{ .DriverStatus }}'
-[[driver-type io.containerd.snapshotter.v1]]
+$ sudo systemctl edit docker.service
 ```
 
-Docker Engine uses the `overlayfs` containerd snapshotter by default.
+Add the following in the editor that opens:
+
+```ini
+[Service]
+Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=100GB"
+```
+
+Save and close the editor, then restart the daemon:
+
+```console
+$ sudo systemctl restart docker
+```
+
+If the overlay2 content is under 100GB, the daemon switches to the containerd
+image store on restart. The overlay2 data remains on disk.
+
+> [!NOTE]
+> Migrating with existing data leaves that data inaccessible until you switch
+> back to the overlay2 driver. The data isn't deleted, just hidden. If you have
+> local images you want to migrate to the containerd image store, export them
+> first with `docker save` or push them to a registry.
+
+## Additional resources
+
+To learn more about the containerd image store and its capabilities in Docker
+Desktop, see
+[containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md).
diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md
@@ -1,6 +1,6 @@
 ---
 description: Learn the technologies that support storage drivers.
-keywords: container, storage, driver, btrfs, overlayfs, vfs, zfs
+keywords: container, storage, driver, btrfs, overlayfs, vfs, zfs, containerd
 title: Storage drivers
 weight: 40
 aliases:
@@ -9,6 +9,16 @@ aliases:
   - /engine/userguide/storagedriver/imagesandcontainers/
 ---
 
+> [!NOTE]
+> Docker Engine 29.0 and later uses the
+> [containerd image store](../containerd.md) by default for fresh installations.
+> The containerd image store uses snapshotters instead of the classic storage
+> drivers described on this page. If you're running a fresh installation of
+> Docker Engine 29.0 or later, or if you've migrated to the containerd image
+> store, this page provides background on how image layers work but the
+> implementation details differ. For information about the containerd image
+> store, see [containerd image store](../containerd.md).
+
 To use storage drivers effectively, it's important to know how Docker builds and
 stores images, and how these images are used by containers. You can use this
 information to make informed choices about the best way to persist data from
diff --git a/content/manuals/engine/storage/drivers/overlayfs-driver.md b/content/manuals/engine/storage/drivers/overlayfs-driver.md
@@ -12,13 +12,17 @@ This page refers to the Linux kernel driver as `OverlayFS` and to the Docker
 storage driver as `overlay2`.
 
 > [!NOTE]
->
+> Docker Engine 29.0 and later uses the
+> [containerd image store](/manuals/engine/storage/containerd.md) by default.
+> The `overlay2` driver is a legacy storage driver. For more information, see
+> [Select a storage driver](/manuals/engine/storage/drivers/select-storage-driver.md).
+
+> [!NOTE]
 > For `fuse-overlayfs` driver, check [Rootless mode documentation](/manuals/engine/security/rootless.md).
 
 ## Prerequisites
 
-OverlayFS is the recommended storage driver, and supported if you meet the following
-prerequisites:
+The `overlay2` driver is supported if you meet the following prerequisites:
 
 - Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using
   version 3.10.0-514 of the kernel or higher.
diff --git a/content/manuals/engine/storage/drivers/select-storage-driver.md b/content/manuals/engine/storage/drivers/select-storage-driver.md
diff --git a/data/summary.yaml b/data/summary.yaml
