From f05e503aecc64bedebe6b21cb87c3d976e74c3de Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 17 Jun 2015 16:06:39 +0100 Subject: [PATCH] Mention network driver plugins and point to protocol docs Signed-off-by: Michael Bridgen Signed-off-by: Tom Denham --- experimental/README.md | 3 +- experimental/plugin_api.md | 118 -------------------------------- experimental/plugins.md | 13 +++- experimental/plugins_network.md | 45 ++++++++++++ experimental/plugins_volume.md | 118 ++++++++++++++++++++++++++++++++ 5 files changed, 175 insertions(+), 122 deletions(-) create mode 100644 experimental/plugins_network.md diff --git a/experimental/README.md b/experimental/README.md index 772cf1cc0b..256b8204f8 100644 --- a/experimental/README.md +++ b/experimental/README.md @@ -45,7 +45,8 @@ Unlike the regular Docker binary, the experimental channels is built and updated ## Current experimental features * [Support for Docker plugins](plugins.md) - * [Volume plugins](plugins_volume.md) +* [Volume plugins](plugins_volume.md) +* [Network plugins](plugins_network.md) * [Native Multi-host networking](networking.md) * [Compose, Swarm and networking integration](compose_swarm_networking.md) diff --git a/experimental/plugin_api.md b/experimental/plugin_api.md index 9309b28468..1b7bbc7055 100644 --- a/experimental/plugin_api.md +++ b/experimental/plugin_api.md @@ -95,124 +95,6 @@ Plugins are activated via the following "handshake" API call. Responds with a list of Docker subsystems which this plugin implements. After activation, the plugin will then be sent events from this subsystem. -## Volume API - -If a plugin registers itself as a `VolumeDriver` (see above) then it is -expected to provide writeable paths on the host filesystem for the Docker -daemon to provide to containers to consume. - -The Docker daemon handles bind-mounting the provided paths into user -containers. - -### /VolumeDriver.Create - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -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). - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - -### /VolumeDriver.Remove - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Create a volume, given a user specified volume name. - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - -### /VolumeDriver.Mount - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Docker requires the plugin to provide a volume, given a user specified volume -name. This is called once per container start. - -**Response**: -``` -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": null -} -``` - -Respond with the path on the host filesystem where the volume has been made -available, and/or a string error if an error occurred. - -### /VolumeDriver.Path - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Docker needs reminding of the path to the volume on the host. - -**Response**: -``` -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": null -} -``` - -Respond with the path on the host filesystem where the volume has been made -available, and/or a string error if an error occurred. - -### /VolumeDriver.Unmount - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Indication that Docker no longer is using the named volume. This is called once -per container stop. Plugin may deduce that it is safe to deprovision it at -this point. - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - ## Plugin retries Attempts to call a method on a plugin are retried with an exponential backoff diff --git a/experimental/plugins.md b/experimental/plugins.md index 9ba4f92963..15de7b767d 100644 --- a/experimental/plugins.md +++ b/experimental/plugins.md @@ -11,8 +11,8 @@ Plugins extend Docker's functionality. They come in specific types. For example, a [volume plugin](/experimental/plugins_volume.md) might enable Docker volumes to persist across multiple Docker hosts. -Currently Docker supports volume plugins. In the future it will support -additional plugin types. +Currently Docker supports volume and network driver plugins. In the future it +will support additional plugin types. ## Installing a plugin @@ -23,10 +23,17 @@ Follow the instructions in the plugin's documentation. The following plugins exist: * The [Flocker plugin](https://clusterhq.com/docker-plugin/) is a volume plugin -which provides multi-host portable volumes for Docker, enabling you to run + which provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines. +* The [Weave plugin](https://github.com/weaveworks/docker-plugin) is a network + driver plugin which provides a virtual, multi-host network for containers. + +* The [Calico plugin](https://github.com/metaswitch/calico-docker) is a network + driver plugin which provides a multi-host network for containers with routes + distributed by BGP. + ## Troubleshooting a plugin If you are having problems with Docker after loading a plugin, ask the authors diff --git a/experimental/plugins_network.md b/experimental/plugins_network.md new file mode 100644 index 0000000000..755537ef80 --- /dev/null +++ b/experimental/plugins_network.md @@ -0,0 +1,45 @@ +# Experimental: Docker network driver plugins + +Docker supports network driver plugins via +[LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are +implemented as "remote drivers" for LibNetwork, which shares plugin +infrastructure with Docker. In effect this means that network driver plugins +are activated in the same way as other plugins, and use the same kind of +protocol. + +## Using network driver plugins + +The means of installing and running a network driver plugin will depend on the +particular plugin. + +Once running however, network driver plugins are used just like the built-in +network drivers: by being mentioned as a driver in network-oriented Docker +commands. For example, + + docker network create -d weave mynet + +Some network driver plugins are listed in [plugins.md](plugins.md) + +The network thus created is owned by the plugin, so subsequent commands +referring to that network will also be run through the plugin. + +## Network driver plugin protocol + +The network driver protocol, additional to the plugin activation call, is +documented as part of LibNetwork: +[https://github.com/docker/libnetwork/blob/master/docs/remote.md](https://github.com/docker/libnetwork/blob/master/docs/remote.md). + +# Related GitHub PRs and issues + +Please record your feedback in the following issue, on the usual +Google Groups, or the IRC channel #docker-network. + + - [#14083](https://github.com/docker/docker/issues/14083) Feedback on + experimental networking features + +Other pertinent issues: + + - [#13977](https://github.com/docker/docker/issues/13977) UI for using networks + - [#14023](https://github.com/docker/docker/pull/14023) --default-network option + - [#14051](https://github.com/docker/docker/pull/14051) --publish-service option + - [#13441](https://github.com/docker/docker/pull/13441) (Deprecated) Networks API & UI diff --git a/experimental/plugins_volume.md b/experimental/plugins_volume.md index 0690e62547..ebc5491a8c 100644 --- a/experimental/plugins_volume.md +++ b/experimental/plugins_volume.md @@ -34,6 +34,124 @@ The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` field of type `string` allowing to specify the name of the driver. It's default value of `"local"` (the default driver for local volumes). +# Volume plugin protocol + +If a plugin registers itself as a `VolumeDriver` when activated, then it is +expected to provide writeable paths on the host filesystem for the Docker +daemon to provide to containers to consume. + +The Docker daemon handles bind-mounting the provided paths into user +containers. + +### /VolumeDriver.Create + +**Request**: +``` +{ + "Name": "volume_name" +} +``` + +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). + +**Response**: +``` +{ + "Err": null +} +``` + +Respond with a string error if an error occurred. + +### /VolumeDriver.Remove + +**Request**: +``` +{ + "Name": "volume_name" +} +``` + +Create a volume, given a user specified volume name. + +**Response**: +``` +{ + "Err": null +} +``` + +Respond with a string error if an error occurred. + +### /VolumeDriver.Mount + +**Request**: +``` +{ + "Name": "volume_name" +} +``` + +Docker requires the plugin to provide a volume, given a user specified volume +name. This is called once per container start. + +**Response**: +``` +{ + "Mountpoint": "/path/to/directory/on/host", + "Err": null +} +``` + +Respond with the path on the host filesystem where the volume has been made +available, and/or a string error if an error occurred. + +### /VolumeDriver.Path + +**Request**: +``` +{ + "Name": "volume_name" +} +``` + +Docker needs reminding of the path to the volume on the host. + +**Response**: +``` +{ + "Mountpoint": "/path/to/directory/on/host", + "Err": null +} +``` + +Respond with the path on the host filesystem where the volume has been made +available, and/or a string error if an error occurred. + +### /VolumeDriver.Unmount + +**Request**: +``` +{ + "Name": "volume_name" +} +``` + +Indication that Docker no longer is using the named volume. This is called once +per container stop. Plugin may deduce that it is safe to deprovision it at +this point. + +**Response**: +``` +{ + "Err": null +} +``` + +Respond with a string error if an error occurred. + # Related GitHub PRs and issues - [#13161](https://github.com/docker/docker/pull/13161) Volume refactor and external volume plugins