1. docker
  2. Commit f05e503aecc64bedebe6b21cb87c3d976e74c3de
Browse code

Mention network driver plugins and point to protocol docs

Signed-off-by: Michael Bridgen <mikeb@squaremobius.net>
Signed-off-by: Tom Denham <tom.denham@metaswitch.com>

Michael Bridgen authored on 2015/06/18 00:06:39
Showing 5 changed files
experimental/README.md
History View file @ f05e503
... ... 
@@ -45,7 +45,8 @@ Unlike the regular Docker binary, the experimental channels is built and updated
45 45 
 ## Current experimental features
46 46
47 47 
 * [Support for Docker plugins](plugins.md)
48 
-  * [Volume plugins](plugins_volume.md)
48 
+* [Volume plugins](plugins_volume.md)
49 
+* [Network plugins](plugins_network.md)
49 50 
 * [Native Multi-host networking](networking.md)
50 51 
 * [Compose, Swarm and networking integration](compose_swarm_networking.md)
51 52
experimental/plugin_api.md
History View file @ f05e503
... ... 
@@ -95,124 +95,6 @@ Plugins are activated via the following "handshake" API call.
95 95 
 Responds with a list of Docker subsystems which this plugin implements.
96 96 
 After activation, the plugin will then be sent events from this subsystem.
97 97
98 
-## Volume API
99 
-
100 
-If a plugin registers itself as a `VolumeDriver` (see above) then it is
101 
-expected to provide writeable paths on the host filesystem for the Docker
102 
-daemon to provide to containers to consume.
103 
-
104 
-The Docker daemon handles bind-mounting the provided paths into user
105 
-containers.
106 
-
107 
-### /VolumeDriver.Create
108 
-
109 
-**Request**:
110 
-```
111 
-{
112 
-    "Name": "volume_name"
113 
-}
114 
-```
115 
-
116 
-Instruct the plugin that the user wants to create a volume, given a user
117 
-specified volume name.  The plugin does not need to actually manifest the
118 
-volume on the filesystem yet (until Mount is called).
119 
-
120 
-**Response**:
121 
-```
122 
-{
123 
-    "Err": null
124 
-}
125 
-```
126 
-
127 
-Respond with a string error if an error occurred.
128 
-
129 
-### /VolumeDriver.Remove
130 
-
131 
-**Request**:
132 
-```
133 
-{
134 
-    "Name": "volume_name"
135 
-}
136 
-```
137 
-
138 
-Create a volume, given a user specified volume name.
139 
-
140 
-**Response**:
141 
-```
142 
-{
143 
-    "Err": null
144 
-}
145 
-```
146 
-
147 
-Respond with a string error if an error occurred.
148 
-
149 
-### /VolumeDriver.Mount
150 
-
151 
-**Request**:
152 
-```
153 
-{
154 
-    "Name": "volume_name"
155 
-}
156 
-```
157 
-
158 
-Docker requires the plugin to provide a volume, given a user specified volume
159 
-name. This is called once per container start.
160 
-
161 
-**Response**:
162 
-```
163 
-{
164 
-    "Mountpoint": "/path/to/directory/on/host",
165 
-    "Err": null
166 
-}
167 
-```
168 
-
169 
-Respond with the path on the host filesystem where the volume has been made
170 
-available, and/or a string error if an error occurred.
171 
-
172 
-### /VolumeDriver.Path
173 
-
174 
-**Request**:
175 
-```
176 
-{
177 
-    "Name": "volume_name"
178 
-}
179 
-```
180 
-
181 
-Docker needs reminding of the path to the volume on the host.
182 
-
183 
-**Response**:
184 
-```
185 
-{
186 
-    "Mountpoint": "/path/to/directory/on/host",
187 
-    "Err": null
188 
-}
189 
-```
190 
-
191 
-Respond with the path on the host filesystem where the volume has been made
192 
-available, and/or a string error if an error occurred.
193 
-
194 
-### /VolumeDriver.Unmount
195 
-
196 
-**Request**:
197 
-```
198 
-{
199 
-    "Name": "volume_name"
200 
-}
201 
-```
202 
-
203 
-Indication that Docker no longer is using the named volume. This is called once
204 
-per container stop.  Plugin may deduce that it is safe to deprovision it at
205 
-this point.
206 
-
207 
-**Response**:
208 
-```
209 
-{
210 
-    "Err": null
211 
-}
212 
-```
213 
-
214 
-Respond with a string error if an error occurred.
215 
-
216 98 
 ## Plugin retries
217 99
218 100 
 Attempts to call a method on a plugin are retried with an exponential backoff
experimental/plugins.md
History View file @ f05e503
... ... 
@@ -11,8 +11,8 @@ Plugins extend Docker's functionality.  They come in specific types.  For
11 11 
 example, a [volume plugin](/experimental/plugins_volume.md) might enable Docker
12 12 
 volumes to persist across multiple Docker hosts.
13 13
14 
-Currently Docker supports volume plugins. In the future it will support
15 
-additional plugin types.
14 
+Currently Docker supports volume and network driver plugins. In the future it
15 
+will support additional plugin types.
16 16
17 17 
 ## Installing a plugin
18 18
... ... 
@@ -23,10 +23,17 @@ Follow the instructions in the plugin's documentation.
23 23 
 The following plugins exist:
24 24
25 25 
 * The [Flocker plugin](https://clusterhq.com/docker-plugin/) is a volume plugin
26 
-which provides multi-host portable volumes for Docker, enabling you to run
26 
+  which provides multi-host portable volumes for Docker, enabling you to run
27 27 
   databases and other stateful containers and move them around across a cluster
28 28 
   of machines.
29 29
30 
+* The [Weave plugin](https://github.com/weaveworks/docker-plugin) is a network
31 
+  driver plugin which provides a virtual, multi-host network for containers.
32 
+
33 
+* The [Calico plugin](https://github.com/metaswitch/calico-docker) is a network
34 
+  driver plugin which provides a multi-host network for containers with routes
35 
+  distributed by BGP.
36 
+
30 37 
 ## Troubleshooting a plugin
31 38
32 39 
 If you are having problems with Docker after loading a plugin, ask the authors
experimental/plugins_network.md
History View file @ f05e503
33 40 
new file mode 100644
... ... 
@@ -0,0 +1,45 @@
0 
+# Experimental: Docker network driver plugins
1 
+
2 
+Docker supports network driver plugins via
3 
+[LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are
4 
+implemented as "remote drivers" for LibNetwork, which shares plugin
5 
+infrastructure with Docker. In effect this means that network driver plugins
6 
+are activated in the same way as other plugins, and use the same kind of
7 
+protocol.
8 
+
9 
+## Using network driver plugins
10 
+
11 
+The means of installing and running a network driver plugin will depend on the
12 
+particular plugin.
13 
+
14 
+Once running however, network driver plugins are used just like the built-in
15 
+network drivers: by being mentioned as a driver in network-oriented Docker
16 
+commands. For example,
17 
+
18 
+    docker network create -d weave mynet
19 
+
20 
+Some network driver plugins are listed in [plugins.md](plugins.md)
21 
+
22 
+The network thus created is owned by the plugin, so subsequent commands
23 
+referring to that network will also be run through the plugin.
24 
+
25 
+## Network driver plugin protocol
26 
+
27 
+The network driver protocol, additional to the plugin activation call, is
28 
+documented as part of LibNetwork:
29 
+[https://github.com/docker/libnetwork/blob/master/docs/remote.md](https://github.com/docker/libnetwork/blob/master/docs/remote.md).
30 
+
31 
+# Related GitHub PRs and issues
32 
+
33 
+Please record your feedback in the following issue, on the usual
34 
+Google Groups, or the IRC channel #docker-network.
35 
+
36 
+ - [#14083](https://github.com/docker/docker/issues/14083) Feedback on
37 
+   experimental networking features
38 
+
39 
+Other pertinent issues:
40 
+
41 
+ - [#13977](https://github.com/docker/docker/issues/13977) UI for using networks
42 
+ - [#14023](https://github.com/docker/docker/pull/14023) --default-network option
43 
+ - [#14051](https://github.com/docker/docker/pull/14051) --publish-service option
44 
+ - [#13441](https://github.com/docker/docker/pull/13441) (Deprecated) Networks API & UI
experimental/plugins_volume.md
History View file @ f05e503
... ... 
@@ -34,6 +34,124 @@ The container creation endpoint (`/containers/create`) accepts a `VolumeDriver`
34 34 
 field of type `string` allowing to specify the name of the driver. It's default
35 35 
 value of `"local"` (the default driver for local volumes).
36 36
37 
+# Volume plugin protocol
38 
+
39 
+If a plugin registers itself as a `VolumeDriver` when activated, then it is
40 
+expected to provide writeable paths on the host filesystem for the Docker
41 
+daemon to provide to containers to consume.
42 
+
43 
+The Docker daemon handles bind-mounting the provided paths into user
44 
+containers.
45 
+
46 
+### /VolumeDriver.Create
47 
+
48 
+**Request**:
49 
+```
50 
+{
51 
+    "Name": "volume_name"
52 
+}
53 
+```
54 
+
55 
+Instruct the plugin that the user wants to create a volume, given a user
56 
+specified volume name.  The plugin does not need to actually manifest the
57 
+volume on the filesystem yet (until Mount is called).
58 
+
59 
+**Response**:
60 
+```
61 
+{
62 
+    "Err": null
63 
+}
64 
+```
65 
+
66 
+Respond with a string error if an error occurred.
67 
+
68 
+### /VolumeDriver.Remove
69 
+
70 
+**Request**:
71 
+```
72 
+{
73 
+    "Name": "volume_name"
74 
+}
75 
+```
76 
+
77 
+Create a volume, given a user specified volume name.
78 
+
79 
+**Response**:
80 
+```
81 
+{
82 
+    "Err": null
83 
+}
84 
+```
85 
+
86 
+Respond with a string error if an error occurred.
87 
+
88 
+### /VolumeDriver.Mount
89 
+
90 
+**Request**:
91 
+```
92 
+{
93 
+    "Name": "volume_name"
94 
+}
95 
+```
96 
+
97 
+Docker requires the plugin to provide a volume, given a user specified volume
98 
+name. This is called once per container start.
99 
+
100 
+**Response**:
101 
+```
102 
+{
103 
+    "Mountpoint": "/path/to/directory/on/host",
104 
+    "Err": null
105 
+}
106 
+```
107 
+
108 
+Respond with the path on the host filesystem where the volume has been made
109 
+available, and/or a string error if an error occurred.
110 
+
111 
+### /VolumeDriver.Path
112 
+
113 
+**Request**:
114 
+```
115 
+{
116 
+    "Name": "volume_name"
117 
+}
118 
+```
119 
+
120 
+Docker needs reminding of the path to the volume on the host.
121 
+
122 
+**Response**:
123 
+```
124 
+{
125 
+    "Mountpoint": "/path/to/directory/on/host",
126 
+    "Err": null
127 
+}
128 
+```
129 
+
130 
+Respond with the path on the host filesystem where the volume has been made
131 
+available, and/or a string error if an error occurred.
132 
+
133 
+### /VolumeDriver.Unmount
134 
+
135 
+**Request**:
136 
+```
137 
+{
138 
+    "Name": "volume_name"
139 
+}
140 
+```
141 
+
142 
+Indication that Docker no longer is using the named volume. This is called once
143 
+per container stop.  Plugin may deduce that it is safe to deprovision it at
144 
+this point.
145 
+
146 
+**Response**:
147 
+```
148 
+{
149 
+    "Err": null
150 
+}
151 
+```
152 
+
153 
+Respond with a string error if an error occurred.
154 
+
37 155 
 # Related GitHub PRs and issues
38 156
39 157 
 - [#13161](https://github.com/docker/docker/pull/13161) Volume refactor and external volume plugins