From 1f10226bfd1aed4967be22f86ee122f4d565f799 Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Fri, 12 Jun 2015 09:25:32 -0400 Subject: [PATCH] Add volume API/CLI Signed-off-by: Brian Goff --- docs/extend/plugins_volume.md | 4 +- docs/reference/commandline/ps.md | 2 +- docs/reference/commandline/volume_create.md | 42 ++++++++++++++++ docs/reference/commandline/volume_inspect.md | 39 +++++++++++++++ docs/reference/commandline/volume_ls.md | 34 +++++++++++++ docs/reference/commandline/volume_rm.md | 22 +++++++++ man/docker-volume-create.1.md | 51 ++++++++++++++++++++ man/docker-volume-inspect.1.md | 26 ++++++++++ man/docker-volume-ls.1.md | 27 +++++++++++ man/docker-volume-rm.1.md | 24 +++++++++ 10 files changed, 269 insertions(+), 2 deletions(-) create mode 100644 docs/reference/commandline/volume_create.md create mode 100644 docs/reference/commandline/volume_inspect.md create mode 100644 docs/reference/commandline/volume_ls.md create mode 100644 docs/reference/commandline/volume_rm.md create mode 100644 man/docker-volume-create.1.md create mode 100644 man/docker-volume-inspect.1.md create mode 100644 man/docker-volume-ls.1.md create mode 100644 man/docker-volume-rm.1.md diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index 2752039d15..41c4dd2194 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -52,13 +52,15 @@ containers. **Request**: ``` { - "Name": "volume_name" + "Name": "volume_name", + "Opts": {} } ``` Instruct the plugin that the user wants to create a volume, given a user specified volume name. The plugin does not need to actually manifest the volume on the filesystem yet (until Mount is called). +Opts is a map of driver specific options passed through from the user request. **Response**: ``` diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 02df110e45..82677a3ada 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -40,7 +40,7 @@ Running `docker ps --no-trunc` showing 2 linked containers. ## Filtering -The filtering flag (`-f` or `--filter)` format is a `key=value` pair. If there is more +The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) The currently supported filters are: diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md new file mode 100644 index 0000000000..52216df2e8 --- /dev/null +++ b/docs/reference/commandline/volume_create.md @@ -0,0 +1,42 @@ + + +# volume create + + Usage: docker volume create [OPTIONS] + + Create a volume + + -d, --driver=local Specify volume driver name + --help=false Print usage + --name= Specify volume name + -o, --opt=map[] Set driver specific options + +Creates a new volume that containers can can consume and store data in. If a name is not specified, Docker generates a random name. You create a volume and then configure the container to use it, for example: + + $ docker volume create --name hello + hello + $ docker run -d -v hello:/world busybox ls /world + +The mount is created inside the container's `/src` directory. Docker does not support relative paths for mount points inside the container. + +Multiple containers can use the same volume in the same time period. This is useful if two containers need access to shared data. For example, if one container writes and the other reads the data. + +## Driver specific options + +Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options: + + $ docker volume create --driver fake --opt tardis=blue --opt timey=wimey + +These options are passed directly to the volume driver. Options for +different volume drivers may do different things (or nothing at all). + +*Note*: The built-in `local` volume driver does not currently accept any options. + diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md new file mode 100644 index 0000000000..f002636593 --- /dev/null +++ b/docs/reference/commandline/volume_inspect.md @@ -0,0 +1,39 @@ + + +# volume inspect + + Usage: docker volume inspect [OPTIONS] [VOLUME NAME] + + Inspect a volume + + -f, --format= Format the output using the given go template. + +Returns information about a volume. By default, this command renders all results +in a JSON array. You can specify an alternate format to execute a given template +is executed for each result. Go's +[text/template](http://golang.org/pkg/text/template/) package describes all the +details of the format. + +Example output: + + $ docker volume create + 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d + $ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d + [ + { + "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d", + "Driver": "local", + "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data" + } + ] + + $ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d + "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data" diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md new file mode 100644 index 0000000000..63e98a47d5 --- /dev/null +++ b/docs/reference/commandline/volume_ls.md @@ -0,0 +1,34 @@ + + +# volume ls + + Usage: docker volume ls [OPTIONS] + + List volumes + + -f, --filter=[] Provide filter values (i.e. 'dangling=true') + --help=false Print usage + -q, --quiet=false Only display volume names + +Lists all the volumes Docker knows about. You can filter using the `-f` or `--filter` flag. The filtering format is a `key=value` pair. To specify more than one filter, pass multiple flags (for example, `--filter "foo=bar" --filter "bif=baz"`) + +There is a single supported filter `dangling=value` which takes a boolean of `true` or `false`. + +Example output: + + $ docker volume create --name rose + rose + $docker volume create --name tyler + tyler + $ docker volume ls + DRIVER VOLUME NAME + local rose + local tyler diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md new file mode 100644 index 0000000000..9b83909a9b --- /dev/null +++ b/docs/reference/commandline/volume_rm.md @@ -0,0 +1,22 @@ + + +# volume rm + + Usage: docker volume rm [OPTIONS] [VOLUME NAME] + + Remove a volume + + --help=false Print usage + +Removes a volume. You cannot remove a volume that is in use by a container. + + $ docker volume rm hello + hello diff --git a/man/docker-volume-create.1.md b/man/docker-volume-create.1.md new file mode 100644 index 0000000000..37089e4d98 --- /dev/null +++ b/man/docker-volume-create.1.md @@ -0,0 +1,51 @@ +% DOCKER(1) Docker User Manuals +% Docker Community +% JULY 2015 +# NAME +docker-volume-create - Create a new volume + +# SYNOPSIS +**docker volume create** +[**-d**|**--driver**[=*local*]] +[**--name**[=**]] +[**-o**|**--opt**[=**]] + +[OPTIONS] + +# DESCRIPTION + +Creates a new volume that containers can consume and store data in. If a name is not specified, Docker generates a random name. You create a volume and then configure the container to use it, for example: + + ``` + $ docker volume create --name hello + hello + $ docker run -d -v hello:/world busybox ls /world + ``` + +The mount is created inside the container's `/src` directory. Docker doesn't not support relative paths for mount points inside the container. + +Multiple containers can use the same volume in the same time period. This is useful if two containers need access to shared data. For example, if one container writes and the other reads the data. + +## Driver specific options + +Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options: + + ``` + $ docker volume create --driver fake --opt tardis=blue --opt timey=wimey + ``` + +These options are passed directly to the volume driver. Options for +different volume drivers may do different things (or nothing at all). + +*Note*: The built-in `local` volume driver does not currently accept any options. + +# OPTIONS +**-d**, **--driver**=[] + Specify volume driver name +**--name**="" + Specify volume name +**-o**, **--opt**=map[] + Set driver specific options + +# HISTORY +July 2015, created by Brian Goff diff --git a/man/docker-volume-inspect.1.md b/man/docker-volume-inspect.1.md new file mode 100644 index 0000000000..cc9d753bdb --- /dev/null +++ b/man/docker-volume-inspect.1.md @@ -0,0 +1,26 @@ +% DOCKER(1) Docker User Manuals +% Docker Community +% JULY 2015 +# NAME +docker-volume-inspect - Get low-level information about a volume + +# SYNOPSIS +**docker volume inspect** +[**-f**|**--format**[=**]] + +[OPTIONS] [VOLUME NAME] + +# DESCRIPTION + +Returns information about a volume. By default, this command renders all results +in a JSON array. You can specify an alternate format to execute a given template +is executed for each result. Go's +http://golang.org/pkg/text/template/ package describes all the details of the +format. + +# OPTIONS +**-f**, **--format**="" + Format the output using the given go template. + +# HISTORY +July 2015, created by Brian Goff diff --git a/man/docker-volume-ls.1.md b/man/docker-volume-ls.1.md new file mode 100644 index 0000000000..785fd62550 --- /dev/null +++ b/man/docker-volume-ls.1.md @@ -0,0 +1,27 @@ +% DOCKER(1) Docker User Manuals +% Docker Community +% JULY 2015 +# NAME +docker-volume-ls - List all volumes + +# SYNOPSIS +**docker volume ls** +[**-f**|**--filter**[=**]] +[**-q**|**--quiet**[=**]] + +[OPTIONS] + +# DESCRIPTION + +Lists all the volumes Docker knows about. You can filter using the `-f` or `--filter` flag. The filtering format is a `key=value` pair. To specify more than one filter, pass multiple flags (for example, `--filter "foo=bar" --filter "bif=baz"`) + +There is a single supported filter `dangling=value` which takes a boolean of `true` or `false`. + +# OPTIONS +**-f**, **--filter**="" + Provide filter values (i.e. 'dangling=true') +**-q**, **--quiet**=false + Only display volume names + +# HISTORY +July 2015, created by Brian Goff diff --git a/man/docker-volume-rm.1.md b/man/docker-volume-rm.1.md new file mode 100644 index 0000000000..ff7c6d3168 --- /dev/null +++ b/man/docker-volume-rm.1.md @@ -0,0 +1,24 @@ +% DOCKER(1) Docker User Manuals +% Docker Community +% JULY 2015 +# NAME +docker-volume-rm - Remove a volume + +# SYNOPSIS +**docker volume rm** + +[OPTIONS] [VOLUME NAME] + +# DESCRIPTION + +Removes a volume. You cannot remove a volume that is in use by a container. + + ``` + $ docker volume rm hello + hello + ``` + +# OPTIONS + +# HISTORY +July 2015, created by Brian Goff