From 91d721aaf485cd99b1fd491b6e153392882a4e72 Mon Sep 17 00:00:00 2001 From: rogaha Date: Mon, 28 Oct 2013 17:24:03 -0700 Subject: [PATCH 1/2] - Added volumes documentation --- docs/sources/use/working_with_volumes.rst | 87 +++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/sources/use/working_with_volumes.rst diff --git a/docs/sources/use/working_with_volumes.rst b/docs/sources/use/working_with_volumes.rst new file mode 100644 index 0000000000..a0e1fbf9ef --- /dev/null +++ b/docs/sources/use/working_with_volumes.rst @@ -0,0 +1,87 @@ +:title: Working with Volumes +:description: How to create and share volumes +:keywords: Examples, Usage, volume, docker, documentation, examples + +.. _volume_def: + +Data Volume +=========== + +.. versionadded:: v0.3.0 + Data volumes have been available since version 1 of the + :doc:`../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 persistant 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 new flag: ``-v``. The parameter ``-v`` can be used more than once in order to create more volumes within the new container. The example below shows the instruction to create a container with two new volumes:: + + docker run -v /var/volume1 -v /var/volume2 shykes/couchdb + +For a Dockerfile, the VOLUME instruction will add one or more new volumes to any container created from the image:: + + VOLUME ["/var/volume1", "/var/volume2"] + + +Create a new container using existing volumes from an existing container: +--------------------------------------------------------------------------- + + +The command below creates a new container which is runnning as daemon ``-d`` and with one volume ``/var/lib/couchdb``:: + + COUCH1=$(sudo docker run -d -v /var/lib/couchdb shykes/couchdb:2013-05-03) + +From the container id of that previous container ``$COUCH1`` it's possible to create new container sharing the same volume using the parameter ``-volumes-from container_id``:: + + COUCH2=$(sudo docker run -d -volumes-from $COUCH1 shykes/couchdb:2013-05-03) + +Now, the second container has the all the information from the first volume. + + +Create a new container which mounts a host directory into it: +------------------------------------------------------------- + + -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro]. + If "host-dir" is missing, then docker creates a new volume. + + This is not available for a Dockerfile due the portability and sharing purpose of it. The [host-dir] volumes is something 100% host dependent and will break on any other machine. + +For example:: + + sudo docker run -v /var/logs:/var/host_logs:ro shykes/couchdb:2013-05-03 + +The command above mounts the host directory ``/var/logs`` into the container with read only permissions as ``/var/host_logs``. + +.. versionadded:: v0.5.0 + +Volumes & persistent data storage +================================= + +Current status +.............. + +Docker has volumes which can be reused from container to container. These volumes have the following limitations: + +* they can't be imported and exported (without piping data into and out of the container) +* they can't be backed up and restored from backups (without piping data into and out of the container) +* they can't be stored on custom storage (e.g.: use high IOPS storage for a volume and regular IOPS storage for others) +* it's not possible to cherry pick the volumes to be used from an old container in a new container +* it's not possible to manage the volumes after deleting the containers to which they were attached \ No newline at end of file From 3061e9f37434fa6bb0714861119ae01d8c4b35fb Mon Sep 17 00:00:00 2001 From: Roberto Gandolfo Hashioka Date: Mon, 4 Nov 2013 13:16:51 -0800 Subject: [PATCH 2/2] - Removed some unconfirmed info - Added reference to the index.rst --- docs/sources/use/index.rst | 1 + docs/sources/use/working_with_volumes.rst | 14 -------------- 2 files changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst index 7d0b3c5a31..914d5a2a21 100644 --- a/docs/sources/use/index.rst +++ b/docs/sources/use/index.rst @@ -19,3 +19,4 @@ Contents: port_redirection puppet host_integration + working_with_volumes diff --git a/docs/sources/use/working_with_volumes.rst b/docs/sources/use/working_with_volumes.rst index a0e1fbf9ef..25febad755 100644 --- a/docs/sources/use/working_with_volumes.rst +++ b/docs/sources/use/working_with_volumes.rst @@ -71,17 +71,3 @@ For example:: The command above mounts the host directory ``/var/logs`` into the container with read only permissions as ``/var/host_logs``. .. versionadded:: v0.5.0 - -Volumes & persistent data storage -================================= - -Current status -.............. - -Docker has volumes which can be reused from container to container. These volumes have the following limitations: - -* they can't be imported and exported (without piping data into and out of the container) -* they can't be backed up and restored from backups (without piping data into and out of the container) -* they can't be stored on custom storage (e.g.: use high IOPS storage for a volume and regular IOPS storage for others) -* it's not possible to cherry pick the volumes to be used from an old container in a new container -* it's not possible to manage the volumes after deleting the containers to which they were attached \ No newline at end of file