Merge pull request #13989 from squaremo/netplugin_docs

Mention network driver plugins and point to protocol docs

experimental/README.md

@@ -62,7 +62,8 @@ After downloading the appropriate binary, you can follow the instructions
 ## 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)
 

experimental/plugin_api.md

@@ -112,124 +112,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

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

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

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