diff --git a/content/storage/_index.md b/content/storage/_index.md index 25de327a54..e265f9b4cf 100644 --- a/content/storage/_index.md +++ b/content/storage/_index.md @@ -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 } diff --git a/content/storage/bind-mounts.md b/content/storage/bind-mounts.md index 1eb2ebe7fe..36363d8969 100644 --- a/content/storage/bind-mounts.md +++ b/content/storage/bind-mounts.md @@ -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 `=` 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 } diff --git a/content/storage/tmpfs.md b/content/storage/tmpfs.md index e269d00583..c19e97ae84 100644 --- a/content/storage/tmpfs.md +++ b/content/storage/tmpfs.md @@ -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 `=` tuple. The `--mount` syntax is more verbose than `--tmpfs`: - The `type` of the mount, which can be [`bind`](bind-mounts.md), `volume`, or diff --git a/content/storage/troubleshooting_volume_errors.md b/content/storage/troubleshooting_volume_errors.md index ccc7fb8973..bf0a68aaf4 100644 --- a/content/storage/troubleshooting_volume_errors.md +++ b/content/storage/troubleshooting_volume_errors.md @@ -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/ --- diff --git a/content/storage/volumes.md b/content/storage/volumes.md index 3e9c92f355..702f0cd092 100644 --- a/content/storage/volumes.md +++ b/content/storage/volumes.md @@ -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 `=` 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=,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 } +> ```console +> $ docker service create \ +> --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 } 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