docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #16488 from dvdksn/storage/block-device-mounts 

storage/block device mounts
This commit is contained in:
David Karlsson 2023-01-25 16:36:48 +01:00 committed by GitHub
parent 58a506a8a9 ad077fb8e9
commit 5424418548
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 120 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
storage/volumes.md
View File

@ -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,11 @@ If you need to specify volume driver options, you must use `--mount`.
> --mount 'type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=local,volume-opt=type=nfs,volume-opt=device=<nfs-server>:<nfs-path>,"volume-opt=o=addr=<nfs-address>,vers=4,soft,timeo=180,bg,tcp,rw"'
> --name myservice \
> <IMAGE>
>
> {: .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 +244,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 +334,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 +465,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 +483,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 +507,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 +518,107 @@ $ 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.
### 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 <mount.volume-opt.type> <mount.volume-opt.device> <mount.dst> -o <mount.volume-opts.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. 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 +643,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 +667,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