diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 1af8e5b489e5..0370dcd7c16e 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -161,6 +161,7 @@ pgAdmin PKG plaintext plist +pluggable Postgres PowerShell Python @@ -183,6 +184,7 @@ Solr SonarQube Splunk SQLite +stargz stdin stdout subfolder diff --git a/content/manuals/engine/daemon/_index.md b/content/manuals/engine/daemon/_index.md index 3b1ee08307a0..32fcab96287a 100644 --- a/content/manuals/engine/daemon/_index.md +++ b/content/manuals/engine/daemon/_index.md @@ -98,13 +98,24 @@ 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 +contents and container snapshots are stored in `/var/lib/containerd`. Other +daemon data (volumes, configs) 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 storage directory using +the `data-root` configuration option. ```json { @@ -112,10 +123,19 @@ You can configure the Docker daemon to use a different directory, using the } ``` -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. +The `data-root` option does not affect image and container data stored in +`/var/lib/containerd` when using the containerd image store. To change the +storage location of containerd snapshotters, use the system containerd +configuration file: + +```toml {title="/etc/containerd/config.toml"} +version = 2 +root = "/mnt/containerd-data" +``` + +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 index d616e3028672..d1ed0a9ee8b4 100644 --- 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,13 @@ Docker Engine API using a named pipe. ## Next steps -- 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. +Learn more about container data persistence: + +- [Volumes](./volumes.md) +- [Bind mounts](./bind-mounts.md) +- [tmpfs mounts](./tmpfs.md) + +Learn more about daemon storage backends: + +- [containerd image store](containerd.md) +- [Storage drivers](drivers/) diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md index 00ceed979dd8..7ae4835220dc 100644 --- a/content/manuals/engine/storage/containerd.md +++ b/content/manuals/engine/storage/containerd.md @@ -3,50 +3,72 @@ 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 +description: Learn about the containerd image store 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 +enable the containerd image store. 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, switching to the containerd image store 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. -The following steps explain how to enable the containerd snapshotters feature. +> [!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. -1. Add the following configuration to your `/etc/docker/daemon.json` - configuration file: +Add the following configuration to your `/etc/docker/daemon.json` file: - ```json - { - "features": { - "containerd-snapshotter": true - } - } - ``` +```json +{ + "features": { + "containerd-snapshotter": true + } +} +``` -2. Save the file. -3. Restart the daemon for the changes to take effect. +Save the file and restart the daemon: - ```console - $ sudo systemctl restart docker - ``` +```console +$ sudo systemctl restart docker +``` -After restarting the daemon, running `docker info` shows that you're using -containerd snapshotter storage drivers. +After restarting the daemon, verify you're using the containerd image store: ```console $ docker info -f '{{ .DriverStatus }}' @@ -54,3 +76,58 @@ $ docker info -f '{{ .DriverStatus }}' ``` Docker Engine uses the `overlayfs` containerd snapshotter by default. + +> [!NOTE] +> When you enable the containerd image store, existing images and containers +> from the overlay2 driver remain on disk but become hidden. They reappear if +> you switch back to overlay2. To use your existing images with the containerd +> image store, push them to a registry first, or use `docker save` to export +> them. + +## Experimental automatic migration + +Docker Engine includes an experimental feature that can automatically switch to +the containerd image store under certain conditions. **This feature is +experimental**. It's provided for those who want to test it, but [starting +fresh](#enable-containerd-image-store-on-docker-engine) is the recommended +approach. + +> [!CAUTION] +> The automatic migration feature is experimental and may not work reliably in +> all scenarios. Create backups before attempting to use it. + +To enable automatic migration, add the `containerd-migration` feature to your +`/etc/docker/daemon.json`: + +```json +{ + "features": { + "containerd-migration": true + } +} +``` + +You can also set the `DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD` environment +variable to make the daemon switch automatically if you have no containers and +your image count is at or below the threshold. For systemd: + +```console +$ sudo systemctl edit docker.service +``` + +Add: + +```ini +[Service] +Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=5" +``` + +If you have no running or stopped containers and 5 or fewer images, the daemon +switches to the containerd image store on restart. Your overlay2 data remains +on disk but becomes hidden. + +## 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 index c6241730936c..1bef91efea88 100644 --- 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 index 5064fb0c32b9..692ea080e830 100644 --- a/content/manuals/engine/storage/drivers/overlayfs-driver.md +++ b/content/manuals/engine/storage/drivers/overlayfs-driver.md @@ -12,13 +12,18 @@ 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 that is superseded by the +> `overlayfs` containerd snapshotter. 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 index 18785775c510..046cb5d68d35 100644 --- a/content/manuals/engine/storage/drivers/select-storage-driver.md +++ b/content/manuals/engine/storage/drivers/select-storage-driver.md @@ -2,7 +2,7 @@ title: Select a storage driver weight: 10 description: Learn how to select the proper storage driver for your container. -keywords: container, storage, driver, btrfs, zfs, overlay, overlay2 +keywords: container, storage, driver, btrfs, zfs, overlay, overlay2, containerd aliases: - /storage/storagedriver/selectadriver/ - /storage/storagedriver/select-storage-driver/ @@ -13,6 +13,14 @@ use Docker volumes to write data. However, some workloads require you to be able to write to the container's writable layer. This is where storage drivers come in. +> [!NOTE] +> Docker Engine 29.0 and later uses the +> [containerd image store](../containerd.md) by default for fresh installations. +> If you upgraded from an earlier version, your daemon continues using the +> classic storage drivers described on this page. You can migrate to the +> containerd image store following the instructions in the +> [containerd image store](../containerd.md) documentation. + Docker supports several storage drivers, using a pluggable architecture. The storage driver controls how images and containers are stored and managed on your Docker host. After you have read the [storage driver overview](./_index.md), the @@ -25,14 +33,15 @@ driver with the best overall performance and stability in the most usual scenari > storage driver is windowsfilter. For more information, see > [windowsfilter](windowsfilter-driver.md). -The Docker Engine provides the following storage drivers on Linux: +The Docker Engine provides the following storage backends on Linux: -| Driver | Description | -| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `overlay2` | `overlay2` is the preferred storage driver for all currently supported Linux distributions, and requires no extra configuration. | -| `fuse-overlayfs` | `fuse-overlayfs`is preferred only for running Rootless Docker on an old host that does not provide support for rootless `overlay2`. The `fuse-overlayfs` driver does not need to be used since Linux kernel 5.11, and `overlay2` works even in rootless mode. Refer to the [rootless mode documentation](/manuals/engine/security/rootless.md) for details. | -| `btrfs` and `zfs` | The `btrfs` and `zfs` storage drivers allow for advanced options, such as creating "snapshots", but require more maintenance and setup. Each of these relies on the backing filesystem being configured correctly. | -| `vfs` | The `vfs` storage driver is intended for testing purposes, and for situations where no copy-on-write filesystem can be used. Performance of this storage driver is poor, and is not generally recommended for production use. | +| Backend | Description | +| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `containerd` (snapshotters) | The default for Docker Engine 29.0 and later. Uses containerd snapshotters for image storage. Supports multi-platform images and attestations. See [containerd image store](../containerd.md) for details. | +| `overlay2` | Classic storage driver. Most widely compatible across all currently supported Linux distributions, and requires no extra configuration. | +| `fuse-overlayfs` | Preferred only for running Rootless Docker on hosts that don't support rootless `overlay2`. Not needed since Linux kernel 5.11, as `overlay2` works in rootless mode. See [rootless mode documentation](/manuals/engine/security/rootless.md) for details. | +| `btrfs` and `zfs` | Allow for advanced options, such as creating snapshots, but require more maintenance and setup. Each relies on the backing filesystem being configured correctly. | +| `vfs` | Intended for testing purposes, and for situations where no copy-on-write filesystem can be used. Performance is poor, and not generally recommended for production use. | @@ -56,32 +65,35 @@ the final decision. ## Supported storage drivers per Linux distribution > [!NOTE] -> > Modifying the storage driver by editing the daemon configuration file isn't -> supported on Docker Desktop. Only the default `overlay2` driver or the -> [containerd storage](/manuals/desktop/features/containerd.md) are supported. The -> following table is also not applicable for the Docker Engine in rootless -> mode. For the drivers available in rootless mode, see the [Rootless mode -> documentation](/manuals/engine/security/rootless.md). - -Your operating system and kernel may not support every storage driver. For -example, `btrfs` is only supported if your system uses `btrfs` as storage. In -general, the following configurations work on recent versions of the Linux +> supported on Docker Desktop. Docker Desktop uses the +> [containerd image store](/manuals/desktop/features/containerd.md) by default +> (version 4.34 and later for clean installs). The following table is also not +> applicable for the Docker Engine in rootless mode. For the drivers available +> in rootless mode, see the +> [Rootless mode documentation](/manuals/engine/security/rootless.md). + +This section applies to classic storage drivers only. If you're using the +containerd image store (the default for Docker Engine 29.0+), see the +[containerd image store documentation](../containerd.md) instead. + +Your operating system and kernel may not support every classic storage driver. +For example, `btrfs` is only supported if your system uses `btrfs` as storage. +In general, the following configurations work on recent versions of the Linux distribution: -| Linux distribution | Recommended storage drivers | Alternative drivers | -| :------------------- | :--------------------------- | :------------------- | -| Ubuntu | `overlay2` | `zfs`, `vfs` | -| Debian | `overlay2` | `vfs` | -| CentOS | `overlay2` | `zfs`, `vfs` | -| Fedora | `overlay2` | `zfs`, `vfs` | -| SLES 15 | `overlay2` | `vfs` | -| RHEL | `overlay2` | `vfs` | - -When in doubt, the best all-around configuration is to use a modern Linux -distribution with a kernel that supports the `overlay2` storage driver, and to -use Docker volumes for write-heavy workloads instead of relying on writing data -to the container's writable layer. +| Linux distribution | Default classic driver | Alternative drivers | +| :------------------- | :---------------------- | :------------------- | +| Ubuntu | `overlay2` | `zfs`, `vfs` | +| Debian | `overlay2` | `vfs` | +| CentOS | `overlay2` | `zfs`, `vfs` | +| Fedora | `overlay2` | `zfs`, `vfs` | +| SLES 15 | `overlay2` | `vfs` | +| RHEL | `overlay2` | `vfs` | + +For systems using classic storage drivers, `overlay2` provides broad +compatibility across Linux distributions. Use Docker volumes for write-heavy +workloads instead of relying on writing data to the container's writable layer. The `vfs` storage driver is usually not the best choice, and primarily intended for debugging purposes in situations where no other storage-driver is supported. diff --git a/data/summary.yaml b/data/summary.yaml index c11b98c934e8..f65e2db4c474 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -141,8 +141,6 @@ Composefile include: requires: Docker Compose [2.20.0](/manuals/compose/releases/release-notes.md#2200) and later Compose sbom: requires: Docker Compose [2.39.0](/manuals/compose/releases/release-notes.md#2390) and later -containerd: - availability: Experimental Dev Environments: availability: Beta Docker Build Cloud: