123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119 |
- :title: Share Directories via Volumes
- :description: How to create and share volumes
- :keywords: Examples, Usage, volume, docker, documentation, examples
- .. _volume_def:
- Share Directories via Volumes
- =============================
- .. versionadded:: v0.3.0
- Data volumes have been available since version 1 of the
- :doc:`../reference/api/docker_remote_api`
- A *data volume* is a specially-designated directory within one or more
- containers that bypasses the :ref:`ufs_def` to provide several useful
- features for persistent or shared data:
- * **Data volumes can be shared and reused between containers.** This
- is the feature that makes data volumes so powerful. You can use it
- for anything from hot database upgrades to custom backup or
- replication tools. See the example below.
- * **Changes to a data volume are made directly**, without the overhead
- of a copy-on-write mechanism. This is good for very large files.
- * **Changes to a data volume will not be included at the next commit**
- because they are not recorded as regular filesystem changes in the
- top layer of the :ref:`ufs_def`
- Each container can have zero or more data volumes.
- Getting Started
- ...............
- Using data volumes is as simple as adding a ``-v`` parameter to the ``docker run``
- command. The ``-v`` parameter can be used more than once in order to
- create more volumes within the new container. To create a new container with
- two new volumes::
- $ docker run -v /var/volume1 -v /var/volume2 busybox true
- This command will create the new container with two new volumes that
- exits instantly (``true`` is pretty much the smallest, simplest program
- that you can run). Once created you can mount its volumes in any other
- container using the ``-volumes-from`` option; irrespecive of whether the
- container is running or not.
- Or, you can use the VOLUME instruction in a Dockerfile to add one or more new
- volumes to any container created from that image::
- # BUILD-USING: docker build -t data .
- # RUN-USING: docker run -name DATA data
- FROM busybox
- VOLUME ["/var/volume1", "/var/volume2"]
- CMD ["/usr/bin/true"]
- Creating and mounting a Data Volume Container
- ---------------------------------------------
- If you have some persistent data that you want to share between containers,
- or want to use from non-persistent containers, its best to create a named
- Data Volume Container, and then to mount the data from it.
- Create a named container with volumes to share (``/var/volume1`` and ``/var/volume2``)::
- $ docker run -v /var/volume1 -v /var/volume2 -name DATA busybox true
- Then mount those data volumes into your application containers::
- $ docker run -t -i -rm -volumes-from DATA -name client1 ubuntu bash
- You can use multiple ``-volumes-from`` parameters to bring together multiple
- data volumes from multiple containers.
- Interestingly, you can mount the volumes that came from the ``DATA`` container in
- yet another container via the ``client1`` middleman container::
- $ docker run -t -i -rm -volumes-from client1 -name client2 ubuntu bash
- This allows you to abstract the actual data source from users of that data,
- similar to :ref:`ambassador_pattern_linking <ambassador_pattern_linking>`.
- If you remove containers that mount volumes, including the initial DATA container,
- or the middleman, the volumes will not be deleted until there are no containers still
- referencing those volumes. This allows you to upgrade, or effectivly migrate data volumes
- between containers.
- Mount a Host Directory as a Container Volume:
- ---------------------------------------------
- ::
- -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
- If ``host-dir`` is missing from the command, then docker creates a new volume.
- If ``host-dir`` is present but points to a non-existent directory on the host,
- Docker will automatically create this directory and use it as the source of the
- bind-mount.
- Note that this is not available from a Dockerfile due the portability and
- sharing purpose of it. The ``host-dir`` volumes are entirely host-dependent and
- might not work on any other machine.
- For example::
- sudo docker run -v /var/logs:/var/host_logs:ro ubuntu bash
- The command above mounts the host directory ``/var/logs`` into the
- container with read only permissions as ``/var/host_logs``.
- .. versionadded:: v0.5.0
- Known Issues
- ............
- * :issue:`2702`: "lxc-start: Permission denied - failed to mount"
- could indicate a permissions problem with AppArmor. Please see the
- issue for a workaround.
- * :issue:`2528`: the busybox container is used to make the resulting container as small and
- simple as possible - whenever you need to interact with the data in the volume
- you mount it into another container.
|