From 0de7f57f79225fb9a6fbcd25bb1e3c38f535b53e Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Tue, 10 Jan 2023 16:29:56 +0100 Subject: [PATCH 1/2] chore: format document --- storage/volumes.md | 46 ++++++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/storage/volumes.md b/storage/volumes.md index df64b6d47d..4fdb13975b 100644 --- a/storage/volumes.md +++ b/storage/volumes.md @@ -3,10 +3,10 @@ description: Using volumes title: Volumes keywords: storage, persistence, data persistence, volumes redirect_from: -- /userguide/dockervolumes/ -- /engine/tutorials/dockervolumes/ -- /engine/userguide/dockervolumes/ -- /engine/admin/volumes/volumes/ + - /userguide/dockervolumes/ + - /engine/tutorials/dockervolumes/ + - /engine/userguide/dockervolumes/ + - /engine/admin/volumes/volumes/ --- Volumes are the preferred mechanism for persisting data generated by and used @@ -50,6 +50,7 @@ If you need to specify volume driver options, you must use `--mount`. - **`-v` or `--volume`**: Consists of three fields, separated by colon characters (`:`). The fields must be in the correct order, and the meaning of each field is not immediately obvious. + - In the case of named volumes, the first field is the name of the volume, and is unique on a given host machine. For anonymous volumes, the first field is omitted. @@ -90,11 +91,10 @@ If you need to specify volume driver options, you must use `--mount`. > --mount 'type=volume,src=,dst=,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:,"volume-opt=o=addr=,vers=4,soft,timeo=180,bg,tcp,rw"' > --name myservice \ > -> {: .warning} - +{: .warning} The examples below show both the `--mount` and `-v` syntax where possible, and - `--mount` is presented first. +`--mount` is presented first. ### Differences between `-v` and `--mount` behavior @@ -243,7 +243,9 @@ volumes: external: true ``` -For more information about using volumes with Compose, refer to the [Volumes](../compose/compose-file/index.md#volumes) section in the Compose specification. +For more information about using volumes with Compose, refer to the +[Volumes](../compose/compose-file/index.md#volumes) +section in the Compose specification. ### Start a service with volumes @@ -331,7 +333,6 @@ $ docker run -d \ After running either of these examples, run the following commands to clean up the containers and volumes. Note volume removal is a separate step. - ```console $ docker container stop nginxtest @@ -463,12 +464,13 @@ $ docker volume create --driver vieux/sshfs \ ### Start a container which creates a volume using a volume driver The following example specifies an SSH password. However, if the two hosts have -shared keys configured, you can exclude the password. Each volume driver may have zero or more configurable options. +shared keys configured, you can exclude the password. +Each volume driver may have zero or more configurable options. > **Note:** > -> If the volume driver requires you to pass any options, you must use the `--mount` flag to mount the volume, and not `-v`. - +> If the volume driver requires you to pass any options, +> you must use the `--mount` flag to mount the volume, and not `-v`. ```console $ docker run -d \ @@ -480,7 +482,9 @@ $ docker run -d \ ### Create a service which creates an NFS volume -The following example shows how you can create an NFS volume when creating a service. It uses `10.0.0.10` as the NFS server and `/var/docker-nfs` as the exported directory on the NFS server. Note that the volume driver specified is `local`. +The following example shows how you can create an NFS volume when creating a service. +It uses `10.0.0.10` as the NFS server and `/var/docker-nfs` as the exported directory on the NFS server. +Note that the volume driver specified is `local`. #### NFSv3 @@ -502,7 +506,8 @@ $ docker service create -d \ ### Create CIFS/Samba volumes -You can mount a Samba share directly in docker without configuring a mount point on your host. +You can mount a Samba share directly in Docker without configuring a mount point on your host. + ```console $ docker volume create \ --driver local \ @@ -512,12 +517,13 @@ $ docker volume create \ --name cif-volume ``` -Notice the `addr` option is required if using a hostname instead of an IP so docker can perform the hostname lookup. +The `addr` option is required if you specify a hostname instead of an IP. +This lets Docker perform the hostname lookup. ## Back up, restore, or migrate data volumes -Volumes are useful for backups, restores, and migrations. Use the -`--volumes-from` flag to create a new container that mounts that volume. +Volumes are useful for backups, restores, and migrations. +Use the `--volumes-from` flag to create a new container that mounts that volume. ### Back up a volume @@ -542,8 +548,8 @@ the `dbdata` volume. ### Restore volume from a backup -With the backup just created, you can restore it to the same container, or to -another container that you created elsewhere. +With the backup just created, you can restore it to the same container, +or to another container that you created elsewhere. For example, create a new container named `dbstore2`: @@ -566,7 +572,7 @@ A Docker data volume persists after you delete a container. There are two types of volumes to consider: - Named volumes have a specific source from outside the container, for example, `awesome:/bar`. -- Anonymous volumes have no specific source, therefore, when the container is deleted, you can instruct the Docker Engine daemon to remove them. +- Anonymous volumes have no specific source. Therefore, when the container is deleted, you can instruct the Docker Engine daemon to remove them. ### Remove anonymous volumes From ad077fb8e9d618aa03df11b9fb6f590668343c66 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Tue, 10 Jan 2023 16:53:28 +0100 Subject: [PATCH 2/2] storage: added block storage mount example Signed-off-by: David Karlsson --- storage/volumes.md | 97 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/storage/volumes.md b/storage/volumes.md index 4fdb13975b..576f4a4b57 100644 --- a/storage/volumes.md +++ b/storage/volumes.md @@ -91,7 +91,8 @@ If you need to specify volume driver options, you must use `--mount`. > --mount 'type=volume,src=,dst=,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:,"volume-opt=o=addr=,vers=4,soft,timeo=180,bg,tcp,rw"' > --name myservice \ > -{: .warning} +> +> {: .warning} The examples below show both the `--mount` and `-v` syntax where possible, and `--mount` is presented first. @@ -520,6 +521,100 @@ $ docker volume create \ The `addr` option is required if you specify a hostname instead of an IP. This lets Docker perform the hostname lookup. +### Block storage devices + +You can mount a block storage device, such as an external drive or a drive partition, to a container. +The following example shows how to create and use a file as a block storage device, +and how to mount the block device as a container volume. + +> **Important** +> +> The following procedure is only an example. +> The solution illustrated here isn't recommended as a general practice. +> Don't attempt this approach unless you're very confident about what you're doing. +{: .important } + +#### How mounting block devices works + +Under the hood, the `--mount` flag using the `local` storage driver invokes the +Linux `mount` syscall and forwards the options you pass to it unaltered. +Docker doesn't implement any additional functionality on top of the native mount features supported by the Linux kernel. + +If you're familiar with the +[Linux `mount` command](https://man7.org/linux/man-pages/man8/mount.8.html), +you can think of the `--mount` options as being forwarded to the `mount` command in the following manner: + +```console +$ mount -t -o +``` + +To illustrate this further, consider the following `mount` command example. +This command mounts the `/dev/loop5` device to the path `/external-drive` on the system. + +```console +$ mount -t ext4 /dev/loop5 /external-drive +``` + +The following `docker run` command achieves a similar result, from the point of view of the container being run. +Running a container with this `--mount` option sets up the mount in the same way as if you had executed the +`mount` command from the previous example. + +```console +$ docker run \ + --mount='type=volume,dst=/external-drive,volume-driver=local,volume-opt=device=/dev/loop5,volume-opt=type=ext4' +``` + +You can't execute the `mount` command inside the container directly, +because the container is unable to access the `/dev/loop5` device. +That's why we're using the `--mount` option for the `docker run` command instead. + +#### Example: Mounting a block device in a container + +The following steps create an `ext4` filesystem and mounts it into a container. +The filesystem support of your system depends on the version of the Linux kernel you are using. + +1. Create a file and allocate some space to it: + + ```console + $ fallocate -f 1G disk.raw + ``` + +2. Build a filesystem onto the `disk.raw` file: + + ```console + $ mkfs.ext4 disk.raw + ``` + +3. Create a loop device: + + ```console + $ losetup -f --show disk.raw + /dev/loop5 + ``` + + > **Note** + > + > `losetup` creates an ephemeral loop device that's removed after + > system reboot, or manually removed with `losetup -d`. + +4. Run a container that mounts the loop device as a volume: + + ```console + $ docker run -it --rm \ + --mount='type=volume,dst=/external-drive,volume-driver=local,volume-opt=device=/dev/loop5,volume-opt=type=ext4' \ + ubuntu bash + ``` + + When the container starts, the path `/external-drive` mounts the + `disk.raw` file from the host filesystem as a block device. + +5. When you're done, and the device is unmounted from the container, + detach the loop device to remove the device from the host system: + + ```console + $ losetup -d /dev/loop5 + ``` + ## Back up, restore, or migrate data volumes Volumes are useful for backups, restores, and migrations.