Merge pull request #22001 from thaJeztah/more-docs-cherries
More docs cherry-picks
This commit is contained in:
commit
4a6f2274be
3 changed files with 185 additions and 116 deletions
|
@ -195,17 +195,17 @@ options for `zfs` start with `zfs`.
|
||||||
to create and manage the thin-pool volume. This volume is then handed to Docker
|
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.
|
to exclusively create snapshot volumes needed for images and containers.
|
||||||
|
|
||||||
Managing the thin-pool outside of Docker makes for the most feature-rich
|
Managing the thin-pool outside of Engine makes for the most feature-rich
|
||||||
method of having Docker utilize device mapper thin provisioning as the
|
method of having Docker utilize device mapper thin provisioning as the
|
||||||
backing storage for Docker's containers. The highlights of the lvm-based
|
backing storage for Docker containers. The highlights of the lvm-based
|
||||||
thin-pool management feature include: automatic or interactive thin-pool
|
thin-pool management feature include: automatic or interactive thin-pool
|
||||||
resize support, dynamically changing thin-pool features, automatic thinp
|
resize support, dynamically changing thin-pool features, automatic thinp
|
||||||
metadata checking when lvm activates the thin-pool, etc.
|
metadata checking when lvm activates the thin-pool, etc.
|
||||||
|
|
||||||
As a fallback if no thin pool is provided, loopback files will be
|
As a fallback if no thin pool is provided, loopback files are
|
||||||
created. Loopback is very slow, but can be used without any
|
created. Loopback is very slow, but can be used without any
|
||||||
pre-configuration of storage. It is strongly recommended that you do
|
pre-configuration of storage. It is strongly recommended that you do
|
||||||
not use loopback in production. Ensure your Docker daemon has a
|
not use loopback in production. Ensure your Engine daemon has a
|
||||||
`--storage-opt dm.thinpooldev` argument provided.
|
`--storage-opt dm.thinpooldev` argument provided.
|
||||||
|
|
||||||
Example use:
|
Example use:
|
||||||
|
@ -441,29 +441,33 @@ options for `zfs` start with `zfs`.
|
||||||
|
|
||||||
* `dm.min_free_space`
|
* `dm.min_free_space`
|
||||||
|
|
||||||
Specifies the min free space percent in thin pool require for new device
|
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
|
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
|
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 optoin,
|
free space checking logic. If user does not specify a value for this option,
|
||||||
then default value for this option is 10%.
|
the Engine uses a default value of 10%.
|
||||||
|
|
||||||
Whenever a new thin pool device is created (during docker pull or
|
Whenever a new a thin pool device is created (during `docker pull` or during
|
||||||
during container creation), docker will check minimum free space is
|
container creation), the Engine checks if the minimum free space is
|
||||||
available as specified by this parameter. If that is not the case, then
|
available. If sufficient space is unavailable, then device creation fails
|
||||||
device creation will fail and docker operation will fail.
|
and any relevant `docker` operation fails.
|
||||||
|
|
||||||
One will have to create more free space in thin pool to recover from the
|
To recover from this error, you must create more free space in the thin pool
|
||||||
error. Either delete some of the images and containers from thin pool and
|
to recover from the error. You can create free space by deleting some images
|
||||||
create free space or add more storage to thin pool.
|
and containers from the thin pool. You can also add more storage to the thin
|
||||||
|
pool.
|
||||||
|
|
||||||
For lvm thin pool, one can add more storage to volume group container thin
|
To add more space to a LVM (logical volume management) thin pool, just add
|
||||||
pool and that should automatically resolve it. If loop devices are being
|
more storage to the volume group container thin pool; this should automatically
|
||||||
used, then stop docker, grow the size of loop files and restart docker and
|
resolve any errors. If your configuration uses loop devices, then stop the
|
||||||
that should resolve the issue.
|
Engine daemon, grow the size of loop files and restart the daemon to resolve
|
||||||
|
the issue.
|
||||||
|
|
||||||
Example use:
|
Example use:
|
||||||
|
|
||||||
|
```bash
|
||||||
$ docker daemon --storage-opt dm.min_free_space=10%
|
$ docker daemon --storage-opt dm.min_free_space=10%
|
||||||
|
```
|
||||||
|
|
||||||
Currently supported options of `zfs`:
|
Currently supported options of `zfs`:
|
||||||
|
|
||||||
|
|
|
@ -17,7 +17,9 @@ for image and container management. This article refers to the Device Mapper
|
||||||
storage driver as `devicemapper`, and the kernel framework as `Device Mapper`.
|
storage driver as `devicemapper`, and the kernel framework as `Device Mapper`.
|
||||||
|
|
||||||
|
|
||||||
>**Note**: The [Commercially Supported Docker Engine (CS-Engine) running on RHEL and CentOS Linux](https://www.docker.com/compatibility-maintenance) requires that you use the `devicemapper` storage driver.
|
>**Note**: The [Commercially Supported Docker Engine (CS-Engine) running on RHEL
|
||||||
|
and CentOS Linux](https://www.docker.com/compatibility-maintenance) requires
|
||||||
|
that you use the `devicemapper` storage driver.
|
||||||
|
|
||||||
|
|
||||||
## An alternative to AUFS
|
## An alternative to AUFS
|
||||||
|
@ -206,103 +208,155 @@ mode uses block devices to create the thin pool. The following procedure shows
|
||||||
you how to configure a Docker host to use the `devicemapper` storage driver in
|
you how to configure a Docker host to use the `devicemapper` storage driver in
|
||||||
a `direct-lvm` configuration.
|
a `direct-lvm` configuration.
|
||||||
|
|
||||||
> **Caution:** If you have already run the Docker daemon on your Docker host
|
> **Caution:** If you have already run the Engine daemon on your Docker host
|
||||||
> and have images you want to keep, `push` them Docker Hub or your private
|
> and have images you want to keep, `push` them Docker Hub or your private
|
||||||
> Docker Trusted Registry before attempting this procedure.
|
> Docker Trusted Registry before attempting this procedure.
|
||||||
|
|
||||||
The procedure below will create a 90GB data volume and 4GB metadata volume to
|
The procedure below will create a 90GB data volume and 4GB metadata volume to
|
||||||
use as backing for the storage pool. It assumes that you have a spare block
|
use as backing for the storage pool. It assumes that you have a spare block
|
||||||
device at `/dev/xvdf` with enough free space to complete the task. The device
|
device at `/dev/sdd` with enough free space to complete the task. The device
|
||||||
identifier and volume sizes may be be different in your environment and you
|
identifier and volume sizes may be be different in your environment and you
|
||||||
should substitute your own values throughout the procedure. The procedure also
|
should substitute your own values throughout the procedure.
|
||||||
assumes that the Docker daemon is in the `stopped` state.
|
|
||||||
|
|
||||||
1. Log in to the Docker host you want to configure and stop the Docker daemon.
|
The procedure also assumes that the Engine daemon is in the `stopped` state.
|
||||||
|
Any existing images or data are lost by this process.
|
||||||
|
|
||||||
2. If it exists, delete your existing image store by removing the
|
1. Log in to the Docker host you want to configure.
|
||||||
`/var/lib/docker` directory.
|
2. If it is running, stop the Engine daemon.
|
||||||
|
3. Install the logical volume management version 2.
|
||||||
|
|
||||||
$ sudo rm -rf /var/lib/docker
|
```bash
|
||||||
|
$ yum install lvm2
|
||||||
|
```
|
||||||
|
4. Create a physical volume replacing `/dev/sdd` with your block device.
|
||||||
|
|
||||||
3. Create an LVM physical volume (PV) on your spare block device using the
|
```bash
|
||||||
`pvcreate` command.
|
$ pvcreate /dev/sdd
|
||||||
|
```
|
||||||
|
|
||||||
$ sudo pvcreate /dev/xvdf
|
5. Create a 'docker' volume group.
|
||||||
Physical volume `/dev/xvdf` successfully created
|
|
||||||
|
|
||||||
The device identifier may be different on your system. Remember to
|
```bash
|
||||||
substitute your value in the command above.
|
$ vgcreate docker /dev/sdd
|
||||||
|
```
|
||||||
|
|
||||||
4. Create a new volume group (VG) called `vg-docker` using the PV created in
|
6. Create a thin pool named `thinpool`.
|
||||||
the previous step.
|
|
||||||
|
|
||||||
$ sudo vgcreate vg-docker /dev/xvdf
|
In this example, the data logical is 95% of the 'docker' volume group size.
|
||||||
Volume group `vg-docker` successfully created
|
Leaving this free space allows for auto expanding of either the data or
|
||||||
|
metadata if space runs low as a temporary stopgap.
|
||||||
|
|
||||||
5. Create a new 90GB logical volume (LV) called `data` from space in the
|
```bash
|
||||||
`vg-docker` volume group.
|
$ lvcreate --wipesignatures y -n thinpool docker -l 95%VG
|
||||||
|
$ lvcreate --wipesignatures y -n thinpoolmeta docker -l 1%VG
|
||||||
|
```
|
||||||
|
|
||||||
$ sudo lvcreate -L 90G -n data vg-docker
|
7. Convert the pool to a thin pool.
|
||||||
Logical volume `data` created.
|
|
||||||
|
|
||||||
The command creates an LVM logical volume called `data` and an associated
|
```bash
|
||||||
block device file at `/dev/vg-docker/data`. In a later step, you instruct the
|
$ lvconvert -y --zero n -c 512K --thinpool docker/thinpool --poolmetadata docker/thinpoolmeta
|
||||||
`devicemapper` storage driver to use this block device to store image and
|
```
|
||||||
container data.
|
|
||||||
|
|
||||||
If you receive a signature detection warning, make sure you are working on
|
8. Configure autoextension of thin pools via an `lvm` profile.
|
||||||
the correct devices before continuing. Signature warnings indicate that the
|
|
||||||
device you're working on is currently in use by LVM or has been used by LVM in
|
|
||||||
the past.
|
|
||||||
|
|
||||||
6. Create a new logical volume (LV) called `metadata` from space in the
|
```bash
|
||||||
`vg-docker` volume group.
|
$ vi /etc/lvm/profile/docker-thinpool.profile
|
||||||
|
```
|
||||||
|
|
||||||
$ sudo lvcreate -L 4G -n metadata vg-docker
|
9. Specify 'thin_pool_autoextend_threshold' value.
|
||||||
Logical volume `metadata` created.
|
|
||||||
|
|
||||||
This creates an LVM logical volume called `metadata` and an associated
|
The value should be the percentage of space used before `lvm` attempts
|
||||||
block device file at `/dev/vg-docker/metadata`. In the next step you instruct
|
to autoextend the available space (100 = disabled).
|
||||||
the `devicemapper` storage driver to use this block device to store image and
|
|
||||||
container metadata.
|
|
||||||
|
|
||||||
7. Start the Docker daemon with the `devicemapper` storage driver and the
|
```
|
||||||
`--storage-opt` flags.
|
thin_pool_autoextend_threshold = 80
|
||||||
|
```
|
||||||
|
|
||||||
The `data` and `metadata` devices that you pass to the `--storage-opt`
|
10. Modify the `thin_pool_autoextend_percent` for when thin pool autoextension occurs.
|
||||||
options were created in the previous steps.
|
|
||||||
|
|
||||||
$ sudo docker daemon --storage-driver=devicemapper --storage-opt dm.datadev=/dev/vg-docker/data --storage-opt dm.metadatadev=/dev/vg-docker/metadata &
|
The value's setting is the perentage of space to increase the thin pool (100 =
|
||||||
[1] 2163
|
disabled)
|
||||||
[root@ip-10-0-0-75 centos]# INFO[0000] Listening for HTTP on unix (/var/run/docker.sock)
|
|
||||||
INFO[0027] Option DefaultDriver: bridge
|
|
||||||
INFO[0027] Option DefaultNetwork: bridge
|
|
||||||
<output truncated>
|
|
||||||
INFO[0027] Daemon has completed initialization
|
|
||||||
INFO[0027] Docker daemon commit=1b09a95-unsupported graphdriver=aufs version=1.11.0-dev
|
|
||||||
|
|
||||||
It is also possible to set the `--storage-driver` and `--storage-opt` flags
|
```
|
||||||
in the Docker config file and start the daemon normally using the `service` or
|
thin_pool_autoextend_percent = 20
|
||||||
`systemd` commands.
|
```
|
||||||
|
|
||||||
8. Use the `docker info` command to verify that the daemon is using `data` and
|
11. Check your work, your `docker-thinpool.profile` file should appear similar to the following:
|
||||||
`metadata` devices you created.
|
|
||||||
|
|
||||||
$ sudo docker info
|
An example `/etc/lvm/profile/docker-thinpool.profile` file:
|
||||||
INFO[0180] GET /v1.20/info
|
|
||||||
Containers: 0
|
```
|
||||||
Images: 0
|
activation {
|
||||||
Storage Driver: devicemapper
|
thin_pool_autoextend_threshold=80
|
||||||
Pool Name: docker-202:1-1032-pool
|
thin_pool_autoextend_percent=20
|
||||||
Pool Blocksize: 65.54 kB
|
}
|
||||||
Backing Filesystem: xfs
|
```
|
||||||
Data file: /dev/vg-docker/data
|
|
||||||
Metadata file: /dev/vg-docker/metadata
|
12. Apply your new lvm profile
|
||||||
[...]
|
|
||||||
|
```bash
|
||||||
|
$ lvchange --metadataprofile docker-thinpool docker/thinpool
|
||||||
|
```
|
||||||
|
|
||||||
|
13. Verify the `lv` is monitored.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ lvs -o+seg_monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
14. If Engine was previously started, clear your graph driver directory.
|
||||||
|
|
||||||
|
Clearing your graph driver removes any images and containers in your Docker
|
||||||
|
installation.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ rm -rf /var/lib/docker/*
|
||||||
|
```
|
||||||
|
|
||||||
|
14. Configure the Engine daemon with specific devicemapper options.
|
||||||
|
|
||||||
|
There are two ways to do this. You can set options on the commmand line if you start the daemon there:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
--storage-driver=devicemapper --storage-opt=dm.thinpooldev=/dev/mapper/docker-thinpool --storage-opt dm.use_deferred_removal=true
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also set them for startup in the `daemon.json` configuration, for example:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"storage-driver": "devicemapper",
|
||||||
|
"storage-opts": [
|
||||||
|
"dm.thinpooldev=/dev/mapper/docker-thinpool",
|
||||||
|
"dm.use_deferred_removal=true"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
15. Start the Engine daemon.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ systemctl start docker
|
||||||
|
```
|
||||||
|
|
||||||
|
After you start the Engine daemon, ensure you monitor your thin pool and volume
|
||||||
|
group free space. While the volume group will auto-extend, it can still fill
|
||||||
|
up. To monitor logical volumes, use `lvs` without options or `lvs -a` to see tha
|
||||||
|
data and metadata sizes. To monitor volume group free space, use the `vgs` command.
|
||||||
|
|
||||||
|
Logs can show the auto-extension of the thin pool when it hits the threshold, to
|
||||||
|
view the logs use:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
journalctl -fu dm-event.service
|
||||||
|
```
|
||||||
|
|
||||||
|
If you run into repeated problems with thin pool, you can use the
|
||||||
|
`dm.min_free_space` option to tune the Engine behavior. This value ensures that
|
||||||
|
operations fail with a warning when the free space is at or near the minimum.
|
||||||
|
For information, see <a
|
||||||
|
href="https://docs.docker.com/engine/reference/commandline/daemon/#storage-driver-options"
|
||||||
|
target="_blank">the storage driver options in the Engine daemon reference</a>.
|
||||||
|
|
||||||
The output of the command above shows the storage driver as `devicemapper`.
|
|
||||||
The last two lines also confirm that the correct devices are being used for
|
|
||||||
the `Data file` and the `Metadata file`.
|
|
||||||
|
|
||||||
### Examine devicemapper structures on the host
|
### Examine devicemapper structures on the host
|
||||||
|
|
||||||
|
@ -410,3 +464,4 @@ data volumes.
|
||||||
* [Select a storage driver](selectadriver.md)
|
* [Select a storage driver](selectadriver.md)
|
||||||
* [AUFS storage driver in practice](aufs-driver.md)
|
* [AUFS storage driver in practice](aufs-driver.md)
|
||||||
* [Btrfs storage driver in practice](btrfs-driver.md)
|
* [Btrfs storage driver in practice](btrfs-driver.md)
|
||||||
|
* [daemon reference](../../reference/commandline/daemon#storage-driver-options)
|
||||||
|
|
|
@ -269,19 +269,27 @@ allocating images and container snapshots.
|
||||||
|
|
||||||
Specifies a custom block storage device to use for the thin pool.
|
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
|
If using a block device for device mapper storage, it is best to use `lvm`
|
||||||
`lvm` to create and manage the thin-pool volume. This volume is then
|
to create and manage the thin-pool volume. This volume is then handed to Docker
|
||||||
handed to Docker to create snapshot volumes needed for images and
|
to exclusively create snapshot volumes needed for images and containers.
|
||||||
containers.
|
|
||||||
|
|
||||||
Managing the thin-pool outside of Docker makes for the most feature-rich method
|
Managing the thin-pool outside of Engine makes for the most feature-rich
|
||||||
of having Docker utilize device mapper thin provisioning as the backing storage
|
method of having Docker utilize device mapper thin provisioning as the
|
||||||
for Docker's containers. The highlights of the LVM-based thin-pool management
|
backing storage for Docker containers. The highlights of the lvm-based
|
||||||
feature include: automatic or interactive thin-pool resize support, dynamically
|
thin-pool management feature include: automatic or interactive thin-pool
|
||||||
changing thin-pool features, automatic thinp metadata checking when lvm activates
|
resize support, dynamically changing thin-pool features, automatic thinp
|
||||||
the thin-pool, etc.
|
metadata checking when lvm activates the thin-pool, etc.
|
||||||
|
|
||||||
Example use: `docker daemon --storage-opt dm.thinpooldev=/dev/mapper/thin-pool`
|
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 use:
|
||||||
|
|
||||||
|
$ docker daemon \
|
||||||
|
--storage-opt dm.thinpooldev=/dev/mapper/thin-pool
|
||||||
|
|
||||||
#### dm.basesize
|
#### dm.basesize
|
||||||
|
|
||||||
|
@ -471,27 +479,29 @@ daemon with a supported environment.
|
||||||
|
|
||||||
#### dm.min_free_space
|
#### dm.min_free_space
|
||||||
|
|
||||||
Specifies the min free space percent in thin pool require for new device
|
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
|
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
|
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 optoin,
|
free space checking logic. If user does not specify a value for this option,
|
||||||
then default value for this option is 10%.
|
the Engine uses a default value of 10%.
|
||||||
|
|
||||||
Whenever a new thin pool device is created (during docker pull or
|
Whenever a new a thin pool device is created (during `docker pull` or during
|
||||||
during container creation), docker will check minimum free space is
|
container creation), the Engine checks if the minimum free space is
|
||||||
available as specified by this parameter. If that is not the case, then
|
available. If the space is unavailable, then device creation fails and any
|
||||||
device creation will fail and docker operation will fail.
|
relevant `docker` operation fails.
|
||||||
|
|
||||||
One will have to create more free space in thin pool to recover from the
|
To recover from this error, you must create more free space in the thin pool to
|
||||||
error. Either delete some of the images and containers from thin pool and
|
recover from the error. You can create free space by deleting some images
|
||||||
create free space or add more storage to thin pool.
|
and containers from tge thin pool. You can also add
|
||||||
|
more storage to the thin pool.
|
||||||
|
|
||||||
For lvm thin pool, one can add more storage to volume group container thin
|
To add more space to an LVM (logical volume management) thin pool, just add
|
||||||
pool and that should automatically resolve it. If loop devices are being
|
more storage to the group container thin pool; this should automatically
|
||||||
used, then stop docker, grow the size of loop files and restart docker and
|
resolve any errors. If your configuration uses loop devices, then stop the
|
||||||
that should resolve the issue.
|
Engine daemon, grow the size of loop files and restart the daemon to resolve
|
||||||
|
the issue.
|
||||||
|
|
||||||
Example use: `docker daemon --storage-opt dm.min_free_space=10%`
|
Example use:: `docker daemon --storage-opt dm.min_free_space=10%`
|
||||||
|
|
||||||
## ZFS options
|
## ZFS options
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue