Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update plugin_volume apidocs for v2 

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
This commit is contained in:
Misty Stanley-Jones 2017-01-27 16:51:44 -08:00 committed by Tibor Vass
parent ab7522c939
commit 38ac6860eb
1 changed files with 168 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

252
docs/extend/plugins_volume.md
View File

@ -16,67 +16,86 @@ keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api"
# Write a volume plugin # Write a volume plugin
Docker Engine volume plugins enable Engine deployments to be integrated with Docker Engine volume plugins enable Engine deployments to be integrated with
external storage systems, such as Amazon EBS, and enable data volumes to persist external storage systems such as Amazon EBS, and enable data volumes to persist
beyond the lifetime of a single Engine host. See the beyond the lifetime of a single Docker host. See the
[plugin documentation](legacy_plugins.md) for more information. [plugin documentation](legacy_plugins.md) for more information.
## Changelog ## Changelog
### 1.13.0 ### 1.13.0
- If used as part of the v2 plugin architecture, mountpoints that are part of paths returned by plugin have to be mounted under the directory specified by PropagatedMount in the plugin configuration [#26398](https://github.com/docker/docker/pull/26398) - If used as part of the v2 plugin architecture, mountpoints that are part of
paths returned by the plugin must be mounted under the directory specified by
`PropagatedMount` in the plugin configuration
([#26398](https://github.com/docker/docker/pull/26398))
### 1.12.0 ### 1.12.0
- Add `Status` field to `VolumeDriver.Get` response ([#21006](https://github.com/docker/docker/pull/21006#)) - Add `Status` field to `VolumeDriver.Get` response
- Add `VolumeDriver.Capabilities` to get capabilities of the volume driver([#22077](https://github.com/docker/docker/pull/22077)) ([#21006](https://github.com/docker/docker/pull/21006#))
- Add `VolumeDriver.Capabilities` to get capabilities of the volume driver
([#22077](https://github.com/docker/docker/pull/22077))
### 1.10.0 ### 1.10.0
- Add `VolumeDriver.Get` which gets the details about the volume ([#16534](https://github.com/docker/docker/pull/16534)) - Add `VolumeDriver.Get` which gets the details about the volume
- Add `VolumeDriver.List` which lists all volumes owned by the driver ([#16534](https://github.com/docker/docker/pull/16534)) ([#16534](https://github.com/docker/docker/pull/16534))
- Add `VolumeDriver.List` which lists all volumes owned by the driver
([#16534](https://github.com/docker/docker/pull/16534))
### 1.8.0 ### 1.8.0
- Initial support for volume driver plugins ([#14659](https://github.com/docker/docker/pull/14659)) - Initial support for volume driver plugins
([#14659](https://github.com/docker/docker/pull/14659))
## Command-line changes ## Command-line changes
A volume plugin makes use of the `-v`and `--volume-driver` flag on the `docker run` command. The `-v` flag accepts a volume name and the `--volume-driver` flag a driver type, for example: To give a container access to a volume, use the `--volume` and `--volume-driver`
flags on the `docker container run` command. The `--volume` (or `-v`) flag
accepts a volume name and path on the host, and the `--volume-driver` flag
accepts a driver type.
$ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh ```bash
$ docker volume create --driver=flocker volumename
This command passes the `volumename` through to the volume plugin as a $ docker container run -it --volume volumename:/data busybox sh
user-given name for the volume. The `volumename` must not begin with a `/`. ```
By having the user specify a `volumename`, a plugin can associate the volume ### `--volume`
with an external volume beyond the lifetime of a single container or container
host. This can be used, for example, to move a stateful container from one
server to another.
By specifying a `volumedriver` in conjunction with a `volumename`, users can use plugins such as [Flocker](https://clusterhq.com/docker-plugin/) to manage volumes external to a single host, such as those on EBS. The `--volume` (or `-v`) flag takes a value that is in the format
`<volume_name>:<mountpoint>`. The two parts of the value are
separated by a colon (`:`) character.
- The volume name is a human-readable name for the volume, and cannot begin with
a `/` character. It is referred to as `volume_name` in the rest of this topic.
- The `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the
volume has been made available.
### `volumedriver`
Specifying a `volumedriver` in conjunction with a `volumename` allows you to
use plugins such as [Flocker](https://github.com/ScatterHQ/flocker) to manage
volumes external to a single host, such as those on EBS.
## Create a VolumeDriver ## Create a VolumeDriver
The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` The container creation endpoint (`/containers/create`) accepts a `VolumeDriver`
field of type `string` allowing to specify the name of the driver. It's default field of type `string` allowing to specify the name of the driver. If not
value of `"local"` (the default driver for local volumes). specified, it defaults to `"local"` (the default driver for local volumes).
## Volume plugin protocol ## Volume plugin protocol
If a plugin registers itself as a `VolumeDriver` when activated, then it is If a plugin registers itself as a `VolumeDriver` when activated, it must
expected to provide writeable paths on the host filesystem for the Docker provide the Docker Daemon with writeable paths on the host filesystem. The Docker
daemon to provide to containers to consume. daemon provides these paths to containers to consume. The Docker daemon makes
the volumes available by bind-mounting the provided paths into the containers.
The Docker daemon handles bind-mounting the provided paths into user
containers.
> **Note**: Volume plugins should *not* write data to the `/var/lib/docker/` > **Note**: Volume plugins should *not* write data to the `/var/lib/docker/`
> directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/` > directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/`
> directory is reserved for Docker. > directory is reserved for Docker.
### /VolumeDriver.Create ### `/VolumeDriver.Create`
**Request**: **Request**:
```json ```json
@ -87,9 +106,9 @@ containers.
``` ```
Instruct the plugin that the user wants to create a volume, given a user 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 specified volume name. The plugin does not need to actually manifest the
volume on the filesystem yet (until Mount is called). volume on the filesystem yet (until `Mount` is called).
Opts is a map of driver specific options passed through from the user request. `Opts` is a map of driver specific options passed through from the user request.
**Response**: **Response**:
```json ```json
@ -100,7 +119,7 @@ Opts is a map of driver specific options passed through from the user request.
Respond with a string error if an error occurred. Respond with a string error if an error occurred.
### /VolumeDriver.Remove ### `/VolumeDriver.Remove`
**Request**: **Request**:
```json ```json
@ -109,7 +128,8 @@ Respond with a string error if an error occurred.
} }
``` ```
Delete the specified volume from disk. This request is issued when a user invokes `docker rm -v` to remove volumes associated with a container. Delete the specified volume from disk. This request is issued when a user
invokes `docker rm -v` to remove volumes associated with a container.
**Response**: **Response**:
```json ```json
@ -120,7 +140,7 @@ Delete the specified volume from disk. This request is issued when a user invoke
Respond with a string error if an error occurred. Respond with a string error if an error occurred.
### /VolumeDriver.Mount ### `/VolumeDriver.Mount`
**Request**: **Request**:
```json ```json
@ -131,47 +151,76 @@ Respond with a string error if an error occurred.
``` ```
Docker requires the plugin to provide a volume, given a user specified volume Docker requires the plugin to provide a volume, given a user specified volume
name. This is called once per container start. If the same volume_name is requested name. `Mount` is called once per container start. If the same `volume_name` is requested
more than once, the plugin may need to keep track of each new mount request and provision more than once, the plugin may need to keep track of each new mount request and provision
at the first mount request and deprovision at the last corresponding unmount request. at the first mount request and deprovision at the last corresponding unmount request.
`ID` is a unique ID for the caller that is requesting the mount. `ID` is a unique ID for the caller that is requesting the mount.
**Response**: **Response**:
```json
{
"Mountpoint": "/path/to/directory/on/host",
"Err": ""
}
```
Respond with the path on the host filesystem where the volume has been made - **v1**:
available, and/or a string error if an error occurred.
### /VolumeDriver.Path ```json
{
"Mountpoint": "/path/to/directory/on/host",
"Err": ""
}
```
- **v2**:
```json
{
"Mountpoint": "/path/under/PropagatedMount",
"Err": ""
}
```
`Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume
has been made available.
`Err` is either empty or contains an error string.
### `/VolumeDriver.Path`
**Request**: **Request**:
```json ```json
{ {
"Name": "volume_name" "Name": "volume_name"
} }
``` ```
Docker needs reminding of the path to the volume on the host. Request the path to the volume with the given `volume_name`.
**Response**: **Response**:
```json
{
"Mountpoint": "/path/to/directory/on/host",
"Err": ""
}
```
Respond with the path on the host filesystem where the volume has been made - **v1**:
available, and/or a string error if an error occurred. `Mountpoint` is optional,
however, the plugin may be queried again later if one is not provided.
### /VolumeDriver.Unmount ```json
{
"Mountpoin": "/path/to/directory/on/host",
"Err": ""
}
```
- **v2**:
```json
{
"Mountpoint": "/path/under/PropagatedMount",
"Err": ""
}
```
Respond with the path on the host (v1) or inside the plugin (v2) where the
volume has been made available, and/or a string error if an error occurred.
`Mountpoint` is optional. However, the plugin may be queried again later if one
is not provided.
### `/VolumeDriver.Unmount`
**Request**: **Request**:
```json ```json
@ -181,8 +230,8 @@ however, the plugin may be queried again later if one is not provided.
} }
``` ```
Indication that Docker no longer is using the named volume. This is called once Docker is no longer using the named volume. `Unmount` is called once per
per container stop. Plugin may deduce that it is safe to deprovision it at container stop. Plugin may deduce that it is safe to deprovision the volume at
this point. this point.
`ID` is a unique ID for the caller that is requesting the mount. `ID` is a unique ID for the caller that is requesting the mount.
@ -197,7 +246,7 @@ this point.
Respond with a string error if an error occurred. Respond with a string error if an error occurred.
### /VolumeDriver.Get ### `/VolumeDriver.Get`
**Request**: **Request**:
```json ```json
@ -206,20 +255,36 @@ Respond with a string error if an error occurred.
} }
``` ```
Get the volume info. Get info about `volume_name`.
**Response**: **Response**:
```json
{ - **v1**:
"Volume": {
"Name": "volume_name", ```json
"Mountpoint": "/path/to/directory/on/host", {
"Status": {} "Volume": {
}, "Name": "volume_name",
"Err": "" "Mountpoint": "/path/to/directory/on/host",
} "Status": {}
``` },
"Err": ""
}
```
- **v2**:
```json
{
"Volume": {
"Name": "volume_name",
"Mountpoint": "/path/under/PropagatedMount",
"Status": {}
},
"Err": ""
}
```
Respond with a string error if an error occurred. `Mountpoint` and `Status` are Respond with a string error if an error occurred. `Mountpoint` and `Status` are
optional. optional.
@ -235,17 +300,35 @@ optional.
Get the list of volumes registered with the plugin. Get the list of volumes registered with the plugin.
**Response**: **Response**:
```json
{ - **v1**:
"Volumes": [
{ ```json
"Name": "volume_name", {
"Mountpoint": "/path/to/directory/on/host" "Volumes": [
} {
], "Name": "volume_name",
"Err": "" "Mountpoint": "/path/to/directory/on/host"
} }
``` ],
"Err": ""
}
```
- **v2**:
```json
{
"Volumes": [
{
"Name": "volume_name",
"Mountpoint": "/path/under/PropagatedMount"
}
],
"Err": ""
}
```
Respond with a string error if an error occurred. `Mountpoint` is optional. Respond with a string error if an error occurred. `Mountpoint` is optional.
@ -257,8 +340,9 @@ Respond with a string error if an error occurred. `Mountpoint` is optional.
``` ```
Get the list of capabilities the driver supports. Get the list of capabilities the driver supports.
The driver is not required to implement this endpoint, however, in such cases
the default values will be taken. The driver is not required to implement `Capabilities`. If it is not
implemented, the default values are used.
**Response**: **Response**:
```json ```json
@ -270,7 +354,7 @@ the default values will be taken.
``` ```
Supported scopes are `global` and `local`. Any other value in `Scope` will be Supported scopes are `global` and `local`. Any other value in `Scope` will be
ignored and assumed to be `local`. Scope allows cluster managers to handle the ignored, and `local` is used. `Scope` allows cluster managers to handle the
volume differently, for instance with a scope of `global`, the cluster manager volume in different ways. For instance, a scope of `global`, signals to the
knows it only needs to create the volume once instead of on every engine. More cluster manager that it only needs to create the volume once instead of on each
capabilities may be added in the future. Docker host. More capabilities may be added in the future.