From 5595f577b0f1da17c2ece9f5de2bb21c193876df Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 19 May 2023 01:42:52 +0200 Subject: [PATCH] docs: remove devicemapper Signed-off-by: Sebastiaan van Stijn --- docs/deprecated.md | 27 +- docs/reference/commandline/dockerd.md | 438 +------------------------- 2 files changed, 8 insertions(+), 457 deletions(-) diff --git a/docs/deprecated.md b/docs/deprecated.md index 9a96be8d2e..0e257584be 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -559,11 +559,12 @@ backported), there is no reason to keep maintaining the `overlay` storage driver **Deprecated in Release: v18.09** **Disabled by default in Release: v23.0** +**Removed in Release: v25.0** -The `devicemapper` storage driver is deprecated in favor of `overlay2`, and will -be removed in a future release. Users of the `devicemapper` storage driver are -recommended to migrate to a different storage driver, such as `overlay2`, which -is now the default storage driver. +The `devicemapper` storage driver is deprecated in favor of `overlay2`, and has +been removed in Docker Engine v25.0. Users of the `devicemapper` storage driver +must migrate to a different storage driver, such as `overlay2`, before upgrading +to Docker Engine v25.0. The `devicemapper` storage driver facilitates running Docker on older (3.x) kernels that have no support for other storage drivers (such as overlay2, or btrfs). @@ -572,24 +573,6 @@ Now that support for `overlay2` is added to all supported distros (as they are either on kernel 4.x, or have support for multiple lowerdirs backported), there is no reason to continue maintenance of the `devicemapper` storage driver. -#### Disabled by default in v23.0 - -Docker already prevented deprecated storage drivers from being automatically -selected on new installations, but continued to use these drivers when upgrading -existing installations. Starting with the v23.0 release, the Docker Engine will -fail to start if a deprecated storage driver is used (see [moby#43378](https://github.com/moby/moby/pull/43378): - -```console -failed to start daemon: error initializing graphdriver: prior storage driver -devicemapper is deprecated and will be removed in a future release; update the the daemon -configuration and explicitly choose this storage driver to continue using it; -visit https://docs.docker.com/go/storage-driver/ for more information. -``` - -To continue using the storage driver, update the daemon configuration to use -explicitly use the given storage driver. Users are encouraged to migrate to -different storage driver. - ### Use of reserved namespaces in engine labels **Deprecated in Release: v18.06** diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index b39bdbaa9b..6c49514ec4 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -323,7 +323,7 @@ $ docker -H tcp://127.0.0.1:2375 pull ubuntu ### Daemon storage-driver On Linux, the Docker daemon has support for several different image layer storage -drivers: `overlay2`, `fuse-overlayfs`, `btrfs`, `zfs`, and `devicemapper`. +drivers: `overlay2`, `fuse-overlayfs`, `btrfs`, and `zfs`. `overlay2` is the preferred storage driver for all currently supported Linux distributions, and is selected by default. Unless users have a strong reason to prefer another storage driver, @@ -336,440 +336,8 @@ On Windows, the Docker daemon only supports the `windowsfilter` storage driver. ### Options per storage driver Particular storage-driver can be configured with options specified with -`--storage-opt` flags. Options for `devicemapper` are prefixed with `dm`, -options for `zfs` start with `zfs`, and options for `btrfs` start with `btrfs`. - -#### Devicemapper options - -This is an example of the configuration file for devicemapper on Linux: - -```json -{ - "storage-driver": "devicemapper", - "storage-opts": [ - "dm.thinpooldev=/dev/mapper/thin-pool", - "dm.use_deferred_deletion=true", - "dm.use_deferred_removal=true" - ] -} -``` - -##### `dm.thinpooldev` - -Specifies a custom block storage device to use for the thin pool. - -If using a block device for device mapper storage, it is best to use `lvm` -to create and manage the thin-pool volume. This volume is then handed to Docker -to exclusively create snapshot volumes needed for images and containers. - -Managing the thin-pool outside of Engine makes for the most feature-rich -method of having Docker utilize device mapper thin provisioning as the -backing storage for Docker containers. The highlights of the lvm-based -thin-pool management feature include: automatic or interactive thin-pool -resize support, dynamically changing thin-pool features, automatic thinp -metadata checking when lvm activates the thin-pool, etc. - -As a fallback if no thin pool is provided, loopback files are -created. Loopback is very slow, but can be used without any -pre-configuration of storage. It is strongly recommended that you do -not use loopback in production. Ensure your Engine daemon has a -`--storage-opt dm.thinpooldev` argument provided. - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool -``` - -##### `dm.directlvm_device` - -As an alternative to providing a thin pool as above, Docker can setup a block -device for you. - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.directlvm_device=/dev/xvdf -``` - -##### `dm.thinp_percent` - -Sets the percentage of passed in block device to use for storage. - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.thinp_percent=95 -``` - -##### `dm.thinp_metapercent` - -Sets the percentage of the passed in block device to use for metadata storage. - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.thinp_metapercent=1 -``` - -##### `dm.thinp_autoextend_threshold` - -Sets the value of the percentage of space used before `lvm` attempts to -autoextend the available space [100 = disabled] - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.thinp_autoextend_threshold=80 -``` - -##### `dm.thinp_autoextend_percent` - -Sets the value percentage value to increase the thin pool by when `lvm` -attempts to autoextend the available space [100 = disabled] - -###### Example: - -```console -$ sudo dockerd --storage-opt dm.thinp_autoextend_percent=20 -``` - - -##### `dm.basesize` - -Specifies the size to use when creating the base device, which limits the -size of images and containers. The default value is 10G. Note, thin devices -are inherently "sparse", so a 10G device which is mostly empty doesn't use -10 GB of space on the pool. However, the filesystem will use more space for -the empty case the larger the device is. - -The base device size can be increased at daemon restart which will allow -all future images and containers (based on those new images) to be of the -new base device size. - -###### Examples - -```console -$ sudo dockerd --storage-opt dm.basesize=50G -``` - -This will increase the base device size to 50G. The Docker daemon will throw an -error if existing base device size is larger than 50G. A user can use -this option to expand the base device size however shrinking is not permitted. - -This value affects the system-wide "base" empty filesystem -that may already be initialized and inherited by pulled images. Typically, -a change to this value requires additional steps to take effect: - -```console -$ sudo service docker stop - -$ sudo rm -rf /var/lib/docker - -$ sudo service docker start -``` - - -##### `dm.loopdatasize` - -> **Note** -> -> This option configures devicemapper loopback, which should not -> be used in production. - -Specifies the size to use when creating the loopback file for the -"data" device which is used for the thin pool. The default size is -100G. The file is sparse, so it will not initially take up this -much space. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.loopdatasize=200G -``` - -##### `dm.loopmetadatasize` - -> **Note** -> -> This option configures devicemapper loopback, which should not -> be used in production. - -Specifies the size to use when creating the loopback file for the -"metadata" device which is used for the thin pool. The default size -is 2G. The file is sparse, so it will not initially take up -this much space. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.loopmetadatasize=4G -``` - -##### `dm.fs` - -Specifies the filesystem type to use for the base device. The supported -options are "ext4" and "xfs". The default is "xfs" - -###### Example - -```console -$ sudo dockerd --storage-opt dm.fs=ext4 -``` - -##### `dm.mkfsarg` - -Specifies extra mkfs arguments to be used when creating the base device. - -###### Example - -```console -$ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal" -``` - -##### `dm.mountopt` - -Specifies extra mount options used when mounting the thin devices. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.mountopt=nodiscard -``` - -##### `dm.datadev` - -(Deprecated, use `dm.thinpooldev`) - -Specifies a custom blockdevice to use for data for the thin pool. - -If using a block device for device mapper storage, ideally both `datadev` and -`metadatadev` should be specified to completely avoid using the loopback -device. - -###### Example - -```console -$ sudo dockerd \ - --storage-opt dm.datadev=/dev/sdb1 \ - --storage-opt dm.metadatadev=/dev/sdc1 -``` - -##### `dm.metadatadev` - -(Deprecated, use `dm.thinpooldev`) - -Specifies a custom blockdevice to use for metadata for the thin pool. - -For best performance the metadata should be on a different spindle than the -data, or even better on an SSD. - -If setting up a new metadata pool it is required to be valid. This can be -achieved by zeroing the first 4k to indicate empty metadata, like this: - -```console -$ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 -``` - -###### Example - -```console -$ sudo dockerd \ - --storage-opt dm.datadev=/dev/sdb1 \ - --storage-opt dm.metadatadev=/dev/sdc1 -``` - -##### `dm.blocksize` - -Specifies a custom blocksize to use for the thin pool. The default -blocksize is 64K. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.blocksize=512K -``` - -##### `dm.blkdiscard` - -Enables or disables the use of `blkdiscard` when removing devicemapper -devices. This is enabled by default (only) if using loopback devices and is -required to resparsify the loopback file on image/container removal. - -Disabling this on loopback can lead to *much* faster container removal -times, but will make the space used in `/var/lib/docker` directory not be -returned to the system for other use when containers are removed. - -###### Examples - -```console -$ sudo dockerd --storage-opt dm.blkdiscard=false -``` - -##### `dm.override_udev_sync_check` - -Overrides the `udev` synchronization checks between `devicemapper` and `udev`. -`udev` is the device manager for the Linux kernel. - -To view the `udev` sync support of a Docker daemon that is using the -`devicemapper` driver, run: - -```console -$ docker info -<...> -Udev Sync Supported: true -<...> -``` - -When `udev` sync support is `true`, then `devicemapper` and udev can -coordinate the activation and deactivation of devices for containers. - -When `udev` sync support is `false`, a race condition occurs between -the`devicemapper` and `udev` during create and cleanup. The race condition -results in errors and failures. (For information on these failures, see -[docker#4036](https://github.com/docker/docker/issues/4036)) - -To allow the `docker` daemon to start, regardless of `udev` sync not being -supported, set `dm.override_udev_sync_check` to true: - -```console -$ sudo dockerd --storage-opt dm.override_udev_sync_check=true -``` - -When this value is `true`, the `devicemapper` continues and simply warns -you the errors are happening. - -> **Note** -> -> The ideal is to pursue a `docker` daemon and environment that does -> support synchronizing with `udev`. For further discussion on this -> topic, see [docker#4036](https://github.com/docker/docker/issues/4036). -> Otherwise, set this flag for migrating existing Docker daemons to -> a daemon with a supported environment. - -##### `dm.use_deferred_removal` - -Enables use of deferred device removal if `libdm` and the kernel driver -support the mechanism. - -Deferred device removal means that if device is busy when devices are -being removed/deactivated, then a deferred removal is scheduled on -device. And devices automatically go away when last user of the device -exits. - -For example, when a container exits, its associated thin device is removed. -If that device has leaked into some other mount namespace and can't be -removed, the container exit still succeeds and this option causes the -system to schedule the device for deferred removal. It does not wait in a -loop trying to remove a busy device. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.use_deferred_removal=true -``` - -##### `dm.use_deferred_deletion` - -Enables use of deferred device deletion for thin pool devices. By default, -thin pool device deletion is synchronous. Before a container is deleted, -the Docker daemon removes any associated devices. If the storage driver -can not remove a device, the container deletion fails and daemon returns. - -```console -Error deleting container: Error response from daemon: Cannot destroy container -``` - -To avoid this failure, enable both deferred device deletion and deferred -device removal on the daemon. - -```console -$ sudo dockerd \ - --storage-opt dm.use_deferred_deletion=true \ - --storage-opt dm.use_deferred_removal=true -``` - -With these two options enabled, if a device is busy when the driver is -deleting a container, the driver marks the device as deleted. Later, when -the device isn't in use, the driver deletes it. - -In general it should be safe to enable this option by default. It will help -when unintentional leaking of mount point happens across multiple mount -namespaces. - -##### `dm.min_free_space` - -Specifies the min free space percent in a thin pool require for new device -creation to succeed. This check applies to both free data space as well -as free metadata space. Valid values are from 0% - 99%. Value 0% disables -free space checking logic. If user does not specify a value for this option, -the Engine uses a default value of 10%. - -Whenever a new a thin pool device is created (during `docker pull` or during -container creation), the Engine checks if the minimum free space is -available. If sufficient space is unavailable, then device creation fails -and any relevant `docker` operation fails. - -To recover from this error, you must create more free space in the thin pool -to recover from the error. You can create free space by deleting some images -and containers from the thin pool. You can also add more storage to the thin -pool. - -To add more space to a LVM (logical volume management) thin pool, just add -more storage to the volume group container thin pool; this should automatically -resolve any errors. If your configuration uses loop devices, then stop the -Engine daemon, grow the size of loop files and restart the daemon to resolve -the issue. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.min_free_space=10% -``` - -##### `dm.xfs_nospace_max_retries` - -Specifies the maximum number of retries XFS should attempt to complete -IO when ENOSPC (no space) error is returned by underlying storage device. - -By default XFS retries infinitely for IO to finish and this can result -in unkillable process. To change this behavior one can set -xfs_nospace_max_retries to say 0 and XFS will not retry IO after getting -ENOSPC and will shutdown filesystem. - -###### Example - -```console -$ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0 -``` - -##### `dm.libdm_log_level` - -Specifies the maxmimum `libdm` log level that will be forwarded to the -`dockerd` log (as specified by `--log-level`). This option is primarily -intended for debugging problems involving `libdm`. Using values other than the -defaults may cause false-positive warnings to be logged. - -Values specified must fall within the range of valid `libdm` log levels. At the -time of writing, the following is the list of `libdm` log levels as well as -their corresponding levels when output by `dockerd`. - -| `libdm` Level | Value | `--log-level` | -|---------------|------:|---------------| -| `_LOG_FATAL` | 2 | error | -| `_LOG_ERR` | 3 | error | -| `_LOG_WARN` | 4 | warn | -| `_LOG_NOTICE` | 5 | info | -| `_LOG_INFO` | 6 | info | -| `_LOG_DEBUG` | 7 | debug | - -###### Example - -```console -$ sudo dockerd \ - --log-level debug \ - --storage-opt dm.libdm_log_level=7 -``` +`--storage-opt` flags. Options for `zfs` start with `zfs`, and options for +`btrfs` start with `btrfs`. #### ZFS options