Browse code

Docs: Improve description on volume removal

A comment in https://github.com/docker/docker/issues/6354#issuecomment-74160215
brought to light that the "Managing Data in containers" section contained an
incorrect (or confusing) line;

"Volumes persist until no containers use them"

Which implies that volumes are automatically removed if they are no longer
referenced by a container.

This pull-request attempts to add some information explaining that volumes are
never automatically removed by Docker and adds some extra hints on working
with data volumes.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Sebastiaan van Stijn authored on 2015/02/13 09:17:33
Showing 1 changed files
... ...
@@ -28,7 +28,12 @@ persistent or shared data:
28 28
 - Data volumes can be shared and reused between containers
29 29
 - Changes to a data volume are made directly
30 30
 - Changes to a data volume will not be included when you update an image
31
-- Volumes persist until no containers use them
31
+- Data volumes persist even if the container itself is deleted
32
+
33
+Data volumes are designed to persist data, independent of the container's life 
34
+cycle. Docker will therefore *never* automatically delete volumes when you remove 
35
+a container, nor will it "garbage collect" volumes that are no longer referenced 
36
+by a container.
32 37
 
33 38
 ### Adding a data volume
34 39
 
... ...
@@ -141,6 +146,14 @@ be deleted.  To delete the volume from disk, you must explicitly call
141 141
 `docker rm -v` against the last container with a reference to the volume. This
142 142
 allows you to upgrade, or effectively migrate data volumes between containers.
143 143
 
144
+> **Note:** Docker will not warn you when removing a container *without* 
145
+> providing the `-v` option to delete its volumes. If you remove containers
146
+> without using the `-v` option, you may end up with "dangling" volumes; 
147
+> volumes that are no longer referenced by a container.
148
+> Dangling volumes are difficult to get rid of and can take up a large amount
149
+> of disk space. We're working on improving volume management and you can check
150
+> progress on this in [pull request #8484](https://github.com/docker/docker/pull/8484)
151
+
144 152
 ## Backup, restore, or migrate data volumes
145 153
 
146 154
 Another useful function we can perform with volumes is use them for