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

ENGDOCS-1744 (#18491) 

* ENGDOCS-1744

* tweak
This commit is contained in:
Allie Sadler 2023-10-24 09:17:51 +01:00 committed by GitHub
parent 50b68b6e08
commit c0e64d8116
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 55 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
content/storage/_index.md
View File

@ -1,7 +1,7 @@
---
description: Overview of persisting data in containers
title: Manage data in Docker
keywords: storage, persistence, data persistence, volumes, mounts, bind mounts
keywords: storage, persistence, data persistence, volumes, mounts, bind mounts, tmpfs
aliases:
- engine/admin/volumes/
---
@ -20,14 +20,12 @@ container layer. This means that:
_data volumes_, which write directly to the host filesystem.
Docker has two options for containers to store files on the host machine, so
that the files are persisted even after the container stops: _volumes_, and
_bind mounts_.
that the files are persisted even after the container stops: volumes, and
bind mounts.
Docker also supports containers storing files in-memory on the host machine. Such files are not persisted.
If you're running Docker on Linux, _tmpfs mount_ is used to store files in the host's system memory.
If you're running Docker on Windows, _named pipe_ is used to store files in the host's system memory.
Keep reading for more information about persisting data or taking advantage of in-memory files.
If you're running Docker on Linux, `tmpfs` mount is used to store files in the host's system memory.
If you're running Docker on Windows, named pipe is used to store files in the host's system memory.
## Choose the right type of mount
@ -40,21 +38,21 @@ mounts is to think about where the data lives on the Docker host.
![Types of mounts and where they live on the Docker host](images/types-of-mounts.png)
- **Volumes** are stored in a part of the host filesystem which is _managed by
- Volumes are stored in a part of the host filesystem which is _managed by
Docker_ (`/var/lib/docker/volumes/` on Linux). Non-Docker processes should not
modify this part of the filesystem. Volumes are the best way to persist data
in Docker.
- **Bind mounts** may be stored *anywhere* on the host system. They may even be
- Bind mounts may be stored anywhere on the host system. They may even be
important system files or directories. Non-Docker processes on the Docker host
or a Docker container can modify them at any time.
- **`tmpfs` mounts** are stored in the host system's memory only, and are never
- `tmpfs` mounts are stored in the host system's memory only, and are never
written to the host system's filesystem.
### More details about mount types
- **[Volumes](volumes.md)**: Created and managed by Docker. You can create a
- [Volumes](volumes.md): Created and managed by Docker. You can create a
volume explicitly using the `docker volume create` command, or Docker can
create a volume during container or service creation.
@ -69,31 +67,33 @@ mounts is to think about where the data lives on the Docker host.
and is not removed automatically. You can remove unused volumes using `docker
volume prune`.
When you mount a volume, it may be **named** or **anonymous**. Anonymous
When you mount a volume, it may be named or anonymous. Anonymous
volumes are not given an explicit name when they are first mounted into a
container, so Docker gives them a random name that is guaranteed to be unique
within a given Docker host. Besides the name, named and anonymous volumes
behave in the same ways.
Volumes also support the use of _volume drivers_, which allow you to store
Volumes also support the use of volume drivers, which allow you to store
your data on remote hosts or cloud providers, among other possibilities.
- **[Bind mounts](bind-mounts.md)**: Available since the early days of Docker.
- [Bind mounts](bind-mounts.md): Available since the early days of Docker.
Bind mounts have limited functionality compared to volumes. When you use a
bind mount, a file or directory on the _host machine_ is mounted into a
bind mount, a file or directory on the host machine is mounted into a
container. The file or directory is referenced by its full path on the host
machine. The file or directory does not need to exist on the Docker host
machine. The file or directory doesn't need to exist on the Docker host
already. It is created on demand if it does not yet exist. Bind mounts are
very performant, but they rely on the host machine's filesystem having a
specific directory structure available. If you are developing new Docker
applications, consider using named volumes instead. You can't use
Docker CLI commands to directly manage bind mounts.
> Bind mounts allow access to sensitive files
> **Important**
>
> Bind mounts allow access to sensitive files.
>
> One side effect of using bind mounts, for better or for worse,
> is that you can change the **host** filesystem via processes running in a
> **container**, including creating, modifying, or deleting important system
> is that you can change the host filesystem via processes running in a
> container, including creating, modifying, or deleting important system
> files or directories. This is a powerful ability which can have security
> implications, including impacting non-Docker processes on the host system.
{ .important }

27
content/storage/bind-mounts.md
View File

@ -8,7 +8,7 @@ aliases:
Bind mounts have been around since the early days of Docker. Bind mounts have
limited functionality compared to [volumes](volumes.md). When you use a bind
mount, a file or directory on the _host machine_ is mounted into a container.
mount, a file or directory on the host machine is mounted into a container.
The file or directory is referenced by its absolute path on the host
machine. By contrast, when you use a volume, a new directory is created within
Docker's storage directory on the host machine, and Docker manages that
@ -34,8 +34,9 @@ syntax separates them. Here is a comparison of the syntax for each flag.
> New users should use the `--mount` syntax. Experienced users may
> be more familiar with the `-v` or `--volume` syntax, but are encouraged to
> use `--mount`, because research has shown it to be easier to use.
{ .tip }
- **`-v` or `--volume`**: Consists of three fields, separated by colon characters
- `-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 bind mounts, the first field is the path to the file or
@ -46,7 +47,7 @@ syntax separates them. Here is a comparison of the syntax for each flag.
as `ro`, `z`, and `Z`. These options
are discussed below.
- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
- `--mount`: Consists of multiple key-value pairs, separated by commas and each
consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
than `-v` or `--volume`, but the order of the keys is not significant, and
the value of the flag is easier to understand.
@ -72,15 +73,15 @@ The examples below show both the `--mount` and `-v` syntax where possible, and
### Differences between `-v` and `--mount` behavior
Because the `-v` and `--volume` flags have been a part of Docker for a long
time, their behavior cannot be changed. This means that **there is one behavior
that is different between `-v` and `--mount`.**
time, their behavior cannot be changed. This means that there is one behavior
that is different between `-v` and `--mount`.
If you use `-v` or `--volume` to bind-mount a file or directory that does not
yet exist on the Docker host, `-v` creates the endpoint for you. **It is
always created as a directory.**
yet exist on the Docker host, `-v` creates the endpoint for you. It is
always created as a directory.
If you use `--mount` to bind-mount a file or directory that does not
yet exist on the Docker host, Docker does **not** automatically create it for
yet exist on the Docker host, Docker does not automatically create it for
you, but generates an error.
## Start a container with a bind mount
@ -279,7 +280,7 @@ propagation setting has a recursive counterpoint. In the case of recursion,
consider that `/tmp/a` is also mounted as `/foo`. The propagation settings
control whether `/mnt/a` and/or `/tmp/a` would exist.
> Warning
> **Warning**
>
> Mount propagation doesn't work with Docker Desktop.
{ .warning }
@ -337,7 +338,7 @@ Now if you create `/app/foo/`, `/app2/foo/` also exists.
## Configure the selinux label
If you use `selinux` you can add the `z` or `Z` options to modify the selinux
label of the **host file or directory** being mounted into the container. This
label of the host file or directory being mounted into the container. This
affects the file or directory on the host machine itself and can have
consequences outside of the scope of Docker.
@ -345,11 +346,13 @@ consequences outside of the scope of Docker.
containers.
- The `Z` option indicates that the bind mount content is private and unshared.
Use **extreme** caution with these options. Bind-mounting a system directory
Use extreme caution with these options. Bind-mounting a system directory
such as `/home` or `/usr` with the `Z` option renders your host machine
inoperable and you may need to relabel the host machine files by hand.
> **Important**: When using bind mounts with services, selinux labels
> **Important**
>
> When using bind mounts with services, selinux labels
> (`:Z` and `:z`), as well as `:ro` are ignored. See
> [moby/moby #32579](https://github.com/moby/moby/issues/32579) for details.
{ .important }

4
content/storage/tmpfs.md
View File

@ -35,10 +35,10 @@ containers.
In general, `--mount` is more explicit and verbose. The biggest difference is
that the `--tmpfs` flag does not support any configurable options.
- **`--tmpfs`**: Mounts a `tmpfs` mount without allowing you to specify any
- `--tmpfs`: Mounts a `tmpfs` mount without allowing you to specify any
configurable options, and can only be used with standalone containers.
- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
- `--mount`: Consists of multiple key-value pairs, separated by commas and each
consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
than `--tmpfs`:
- The `type` of the mount, which can be [`bind`](bind-mounts.md), `volume`, or

2
content/storage/troubleshooting_volume_errors.md
View File

@ -1,7 +1,7 @@
---
description: Troubleshooting volume errors
keywords: cadvisor, troubleshooting, volumes, bind-mounts
title: Troubleshoot volume errors
title: Troubleshoot storage errors
aliases:
- /engine/admin/troubleshooting_volume_errors/
---

35
content/storage/volumes.md
View File

@ -49,7 +49,7 @@ syntax separates them. Here is a comparison of the syntax for each flag.
If you need to specify volume driver options, you must use `--mount`.
- **`-v` or `--volume`**: Consists of three fields, separated by colon characters
- `-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
isn't immediately obvious.
@ -61,7 +61,7 @@ If you need to specify volume driver options, you must use `--mount`.
- The third field is optional, and is a comma-separated list of options, such
as `ro`. These options are discussed below.
- **`--mount`**: Consists of multiple key-value pairs, separated by commas and each
- `--mount`: Consists of multiple key-value pairs, separated by commas and each
consisting of a `<key>=<value>` tuple. The `--mount` syntax is more verbose
than `-v` or `--volume`, but the order of the keys isn't significant, and
the value of the flag is easier to understand.
@ -79,7 +79,7 @@ If you need to specify volume driver options, you must use `--mount`.
- The `volume-opt` option, which can be specified more than once, takes a
key-value pair consisting of the option name and its value.
> Escape values from outer CSV parser
> **Warning**
>
> If your volume driver accepts a comma-separated list as an option,
> you must escape the value from the outer CSV parser. To escape a `volume-opt`,
@ -89,17 +89,18 @@ If you need to specify volume driver options, you must use `--mount`.
> For example, the `local` driver accepts mount options as a comma-separated
> list in the `o` parameter. This example shows the correct way to escape the list.
>
> $ docker service create \
> --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 }
> ```console
> $ docker service create \
> --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, with
`--mount` first.
### Differences between `-v` and `--mount` behavior
### Differences between `-v` and `--mount` behavior
As opposed to bind mounts, all options for volumes are available for both
`--mount` and `-v` flags.
@ -111,13 +112,13 @@ Volumes used with services, only support `--mount`.
Unlike a bind mount, you can create and manage volumes outside the scope of any
container.
**Create a volume**:
Create a volume:
```console
$ docker volume create my-vol
```
**List volumes**:
List volumes:
```console
$ docker volume ls
@ -125,7 +126,7 @@ $ docker volume ls
local my-vol
```
**Inspect a volume**:
Inspect a volume:
```console
$ docker volume inspect my-vol
@ -141,7 +142,7 @@ $ docker volume inspect my-vol
]
```
**Remove a volume**:
Remove a volume:
```console
$ docker volume rm my-vol
@ -229,7 +230,7 @@ volumes:
Running `docker compose up` for the first time creates a volume. Docker reuses the same volume when you run the command subsequently.
You can create a volume directly outside of Compose using `docker volume create` and
then reference it inside `docker-compose.yml` as follows:
then reference it inside `compose.yaml` as follows:
```yaml
services:
@ -458,7 +459,7 @@ 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.
> **Note:**
> **Note**
>
> If the volume driver requires you to pass any options,
> you must use the `--mount` flag to mount the volume, and not `-v`.
@ -669,7 +670,7 @@ the Docker Engine removes the `/foo` volume but not the `awesome` volume.
$ docker run --rm -v /foo -v awesome:/bar busybox top
```
> **Note**:
> **Note**
>
> If another container binds the volumes with
> `--volumes-from`, the volume definitions are _copied_ and the