mirror of https://github.com/docker/docs.git
221 lines
11 KiB
Markdown
221 lines
11 KiB
Markdown
---
|
|
description: Overview of persisting data in containers
|
|
title: Manage data in Docker
|
|
keywords: storage, persistence, data persistence, volumes, mounts, bind mounts, tmpfs
|
|
aliases:
|
|
- engine/admin/volumes/
|
|
---
|
|
|
|
By default all files created inside a container are stored on a writable
|
|
container layer. This means that:
|
|
|
|
- The data doesn't persist when that container no longer exists, and it can be
|
|
difficult to get the data out of the container if another process needs it.
|
|
- A container's writable layer is tightly coupled to the host machine
|
|
where the container is running. You can't easily move the data somewhere else.
|
|
- Writing into a container's writable layer requires a
|
|
[storage driver](/storage/storagedriver/) to manage the
|
|
filesystem. The storage driver provides a union filesystem, using the Linux
|
|
kernel. This extra abstraction reduces performance as compared to using
|
|
_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.
|
|
|
|
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.
|
|
|
|
## Choose the right type of mount
|
|
|
|
No matter which type of mount you choose to use, the data looks the same from
|
|
within the container. It is exposed as either a directory or an individual file
|
|
in the container's filesystem.
|
|
|
|
An easy way to visualize the difference among volumes, bind mounts, and `tmpfs`
|
|
mounts is to think about where the data lives on the Docker host.
|
|
|
|
|
|
|
|
- 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
|
|
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
|
|
written to the host system's filesystem.
|
|
|
|
Bind mounts and volumes can both be mounted into containers using the `-v` or
|
|
`--volume` flag, but the syntax for each is slightly different. For `tmpfs`
|
|
mounts, you can use the `--tmpfs` flag. We recommend using the `--mount` flag
|
|
for both containers and services, for bind mounts, volumes, or `tmpfs` mounts,
|
|
as the syntax is more clear.
|
|
|
|
### Volumes
|
|
|
|
Volumes are 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.
|
|
|
|
When you create a volume, it's stored within a directory on the Docker
|
|
host. When you mount the volume into a container, this directory is what's
|
|
mounted into the container. This is similar to the way that bind mounts work,
|
|
except that volumes are managed by Docker and are isolated from the core
|
|
functionality of the host machine.
|
|
|
|
A given volume can be mounted into multiple containers simultaneously. When no
|
|
running container is using a volume, the volume is still available to Docker
|
|
and isn't removed automatically. You can remove unused volumes using `docker
|
|
volume prune`.
|
|
|
|
When you mount a volume, it may be named or anonymous. Anonymous volumes are
|
|
given a random name that's guaranteed to be unique within a given Docker host.
|
|
Just like named volumes, anonymous volumes persist even if you remove the
|
|
container that uses them, except if you use the `--rm` flag when creating the
|
|
container, in which case the anonymous volume is destroyed.
|
|
See [Remove anonymous volumes](volumes.md#remove-anonymous-volumes).
|
|
If you create multiple containers after each other that use anonymous volumes,
|
|
each container creates its own volume.
|
|
Anonymous volumes aren't reused or shared between containers automatically.
|
|
To share an anonymous volume between two or more containers,
|
|
you must mount the anonymous volume using the random volume ID.
|
|
|
|
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 have limited functionality compared to volumes. When you use 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 doesn't need to exist on the Docker host already. It is created on
|
|
demand if it doesn't yet exist. Bind mounts are fast, 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.
|
|
|
|
> **Important**
|
|
>
|
|
> Bind mounts allow write access to files on the host by default.
|
|
>
|
|
> One side effect of using bind mounts 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 }
|
|
|
|
> **Tip**
|
|
>
|
|
> Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase?
|
|
> Check out [Synchronized file shares](../desktop/synchronized-file-sharing.md). It provides fast and flexible host-to-VM file sharing by enhancing bind mount performance through the use of synchronized filesystem caches.
|
|
{ .tip }
|
|
|
|
### tmpfs
|
|
|
|
A `tmpfs` mount isn't persisted on disk, either on the Docker host or within a
|
|
container. It can be used by a container during the lifetime of the container,
|
|
to store non-persistent state or sensitive information. For instance,
|
|
internally, Swarm services use `tmpfs` mounts to mount
|
|
[secrets](../engine/swarm/secrets.md) into a service's containers.
|
|
|
|
### Named pipes
|
|
|
|
[Named pipes](https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes)
|
|
can be used for communication between the Docker host and a container. Common
|
|
use case is to run a third-party tool inside of a container and connect to the
|
|
Docker Engine API using a named pipe.
|
|
|
|
## Good use cases for volumes
|
|
|
|
Volumes are the preferred way to persist data in Docker containers and services.
|
|
Some use cases for volumes include:
|
|
|
|
- Sharing data among multiple running containers. If you don't explicitly create
|
|
it, a volume is created the first time it is mounted into a container. When
|
|
that container stops or is removed, the volume still exists. Multiple
|
|
containers can mount the same volume simultaneously, either read-write or
|
|
read-only. Volumes are only removed when you explicitly remove them.
|
|
|
|
- When the Docker host is not guaranteed to have a given directory or file
|
|
structure. Volumes help you decouple the configuration of the Docker host
|
|
from the container runtime.
|
|
|
|
- When you want to store your container's data on a remote host or a cloud
|
|
provider, rather than locally.
|
|
|
|
- When you need to back up, restore, or migrate data from one Docker
|
|
host to another, volumes are a better choice. You can stop containers using
|
|
the volume, then back up the volume's directory
|
|
(such as `/var/lib/docker/volumes/<volume-name>`).
|
|
|
|
- When your application requires high-performance I/O on Docker Desktop. Volumes
|
|
are stored in the Linux VM rather than the host, which means that the reads and writes
|
|
have much lower latency and higher throughput.
|
|
|
|
- When your application requires fully native file system behavior on Docker
|
|
Desktop. For example, a database engine requires precise control over disk
|
|
flushing to guarantee transaction durability. Volumes are stored in the Linux
|
|
VM and can make these guarantees, whereas bind mounts are remoted to macOS or
|
|
Windows, where the file systems behave slightly differently.
|
|
|
|
## Good use cases for bind mounts
|
|
|
|
In general, you should use volumes where possible. Bind mounts are appropriate
|
|
for the following types of use case:
|
|
|
|
- Sharing configuration files from the host machine to containers. This is how
|
|
Docker provides DNS resolution to containers by default, by mounting
|
|
`/etc/resolv.conf` from the host machine into each container.
|
|
|
|
- Sharing source code or build artifacts between a development environment on
|
|
the Docker host and a container. For instance, you may mount a Maven `target/`
|
|
directory into a container, and each time you build the Maven project on the
|
|
Docker host, the container gets access to the rebuilt artifacts.
|
|
|
|
If you use Docker for development this way, your production Dockerfile would
|
|
copy the production-ready artifacts directly into the image, rather than
|
|
relying on a bind mount.
|
|
|
|
- When the file or directory structure of the Docker host is guaranteed to be
|
|
consistent with the bind mounts the containers require.
|
|
|
|
## Good use cases for tmpfs mounts
|
|
|
|
`tmpfs` mounts are best used for cases when you do not want the data to persist
|
|
either on the host machine or within the container. This may be for security
|
|
reasons or to protect the performance of the container when your application
|
|
needs to write a large volume of non-persistent state data.
|
|
|
|
## Tips for using bind mounts or volumes
|
|
|
|
If you use either bind mounts or volumes, keep the following in mind:
|
|
|
|
- If you mount an **empty volume** into a directory in the container in which files
|
|
or directories exist, these files or directories are propagated (copied)
|
|
into the volume. Similarly, if you start a container and specify a volume which
|
|
does not already exist, an empty volume is created for you.
|
|
This is a good way to pre-populate data that another container needs.
|
|
|
|
- If you mount a **bind mount or non-empty volume** into a directory in the container
|
|
in which some files or directories exist, these files or directories are
|
|
obscured by the mount, just as if you saved files into `/mnt` on a Linux host
|
|
and then mounted a USB drive into `/mnt`. The contents of `/mnt` would be
|
|
obscured by the contents of the USB drive until the USB drive was unmounted.
|
|
The obscured files are not removed or altered, but are not accessible while the
|
|
bind mount or volume is mounted.
|
|
|
|
## Next steps
|
|
|
|
- Learn more about [volumes](volumes.md).
|
|
- Learn more about [bind mounts](bind-mounts.md).
|
|
- Learn more about [tmpfs mounts](tmpfs.md).
|
|
- Learn more about [storage drivers](/storage/storagedriver/), which
|
|
are not related to bind mounts or volumes, but allow you to store data in a
|
|
container's writable layer.
|