working_with_volumes.rst 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119
  1. :title: Share Directories via Volumes
  2. :description: How to create and share volumes
  3. :keywords: Examples, Usage, volume, docker, documentation, examples
  4. .. _volume_def:
  5. Share Directories via Volumes
  6. =============================
  7. .. versionadded:: v0.3.0
  8. Data volumes have been available since version 1 of the
  9. :doc:`../reference/api/docker_remote_api`
  10. A *data volume* is a specially-designated directory within one or more
  11. containers that bypasses the :ref:`ufs_def` to provide several useful
  12. features for persistent or shared data:
  13. * **Data volumes can be shared and reused between containers.** This
  14. is the feature that makes data volumes so powerful. You can use it
  15. for anything from hot database upgrades to custom backup or
  16. replication tools. See the example below.
  17. * **Changes to a data volume are made directly**, without the overhead
  18. of a copy-on-write mechanism. This is good for very large files.
  19. * **Changes to a data volume will not be included at the next commit**
  20. because they are not recorded as regular filesystem changes in the
  21. top layer of the :ref:`ufs_def`
  22. Each container can have zero or more data volumes.
  23. Getting Started
  24. ...............
  25. Using data volumes is as simple as adding a ``-v`` parameter to the ``docker run``
  26. command. The ``-v`` parameter can be used more than once in order to
  27. create more volumes within the new container. To create a new container with
  28. two new volumes::
  29. $ docker run -v /var/volume1 -v /var/volume2 busybox true
  30. This command will create the new container with two new volumes that
  31. exits instantly (``true`` is pretty much the smallest, simplest program
  32. that you can run). Once created you can mount its volumes in any other
  33. container using the ``-volumes-from`` option; irrespecive of whether the
  34. container is running or not.
  35. Or, you can use the VOLUME instruction in a Dockerfile to add one or more new
  36. volumes to any container created from that image::
  37. # BUILD-USING: docker build -t data .
  38. # RUN-USING: docker run -name DATA data
  39. FROM busybox
  40. VOLUME ["/var/volume1", "/var/volume2"]
  41. CMD ["/usr/bin/true"]
  42. Creating and mounting a Data Volume Container
  43. ---------------------------------------------
  44. If you have some persistent data that you want to share between containers,
  45. or want to use from non-persistent containers, its best to create a named
  46. Data Volume Container, and then to mount the data from it.
  47. Create a named container with volumes to share (``/var/volume1`` and ``/var/volume2``)::
  48. $ docker run -v /var/volume1 -v /var/volume2 -name DATA busybox true
  49. Then mount those data volumes into your application containers::
  50. $ docker run -t -i -rm -volumes-from DATA -name client1 ubuntu bash
  51. You can use multiple ``-volumes-from`` parameters to bring together multiple
  52. data volumes from multiple containers.
  53. Interestingly, you can mount the volumes that came from the ``DATA`` container in
  54. yet another container via the ``client1`` middleman container::
  55. $ docker run -t -i -rm -volumes-from client1 -name client2 ubuntu bash
  56. This allows you to abstract the actual data source from users of that data,
  57. similar to :ref:`ambassador_pattern_linking <ambassador_pattern_linking>`.
  58. If you remove containers that mount volumes, including the initial DATA container,
  59. or the middleman, the volumes will not be deleted until there are no containers still
  60. referencing those volumes. This allows you to upgrade, or effectivly migrate data volumes
  61. between containers.
  62. Mount a Host Directory as a Container Volume:
  63. ---------------------------------------------
  64. ::
  65. -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
  66. If ``host-dir`` is missing from the command, then docker creates a new volume.
  67. If ``host-dir`` is present but points to a non-existent directory on the host,
  68. Docker will automatically create this directory and use it as the source of the
  69. bind-mount.
  70. Note that this is not available from a Dockerfile due the portability and
  71. sharing purpose of it. The ``host-dir`` volumes are entirely host-dependent and
  72. might not work on any other machine.
  73. For example::
  74. sudo docker run -v /var/logs:/var/host_logs:ro ubuntu bash
  75. The command above mounts the host directory ``/var/logs`` into the
  76. container with read only permissions as ``/var/host_logs``.
  77. .. versionadded:: v0.5.0
  78. Known Issues
  79. ............
  80. * :issue:`2702`: "lxc-start: Permission denied - failed to mount"
  81. could indicate a permissions problem with AppArmor. Please see the
  82. issue for a workaround.
  83. * :issue:`2528`: the busybox container is used to make the resulting container as small and
  84. simple as possible - whenever you need to interact with the data in the volume
  85. you mount it into another container.