1. docker
  2. Commit 8d0486832dafb775e93dafd1229fcf7e81ee4a28
Browse code

Document in the experimental section

Signed-off-by: Arnaud Porterie <arnaud.porterie@docker.com>
(cherry picked from commit a31633c2707c78c2ffd684a5a3e576f310af0fb5)

Arnaud Porterie authored on 2015/05/23 08:47:28
Showing 3 changed files
docs/sources/experimental/plugin_api.md
History View file @ 8d04868
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,223 @@
0 
+page_title: Plugin API documentation
1 
+page_description: Documentation for writing a Docker plugin.
2 
+page_keywords: docker, plugins, api, extensions
3 
+
4 
+# Docker Plugin API
5 
+
6 
+Docker plugins are out-of-process extensions which add capabilities to the
7 
+Docker Engine.
8 
+
9 
+This page is intended for people who want to develop their own Docker plugin.
10 
+If you just want to learn about or use Docker plugins, look
11 
+[here](/userguide/plugins).
12 
+
13 
+## What plugins are
14 
+
15 
+A plugin is a process running on the same docker host as the docker daemon,
16 
+which registers itself by placing a file in `/usr/share/docker/plugins` (the
17 
+"plugin directory").
18 
+
19 
+Plugins have human-readable names, which are short, lowercase strings. For
20 
+example, `flocker` or `weave`.
21 
+
22 
+Plugins can run inside or outside containers. Currently running them outside
23 
+containers is recommended.
24 
+
25 
+## Plugin discovery
26 
+
27 
+Docker discovers plugins by looking for them in the plugin directory whenever a
28 
+user or container tries to use one by name.
29 
+
30 
+There are two types of files which can be put in the plugin directory.
31 
+
32 
+* `.sock` files are UNIX domain sockets.
33 
+* `.spec` files are text files containing a URL, such as `unix:///other.sock`.
34 
+
35 
+The name of the file (excluding the extension) determines the plugin name.
36 
+
37 
+For example, the `flocker` plugin might create a UNIX socket at
38 
+`/usr/share/docker/plugins/flocker.sock`.
39 
+
40 
+Plugins must be run locally on the same machine as the Docker daemon.  UNIX
41 
+domain sockets are strongly encouraged for security reasons.
42 
+
43 
+## Plugin lifecycle
44 
+
45 
+Plugins should be started before Docker, and stopped after Docker.  For
46 
+example, when packaging a plugin for a platform which supports `systemd`, you
47 
+might use [`systemd` dependencies](
48 
+http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to
49 
+manage startup and shutdown order.
50 
+
51 
+When upgrading a plugin, you should first stop the Docker daemon, upgrade the
52 
+plugin, then start Docker again.
53 
+
54 
+If a plugin is packaged as a container, this may cause issues. Plugins as
55 
+containers are currently considered experimental due to these shutdown/startup
56 
+ordering issues. These issues are mitigated by plugin retries (see below).
57 
+
58 
+## Plugin activation
59 
+
60 
+When a plugin is first referred to -- either by a user referring to it by name
61 
+(e.g.  `docker run --volume-driver=foo`) or a container already configured to
62 
+use a plugin being started -- Docker looks for the named plugin in the plugin
63 
+directory and activates it with a handshake. See Handshake API below.
64 
+
65 
+Plugins are *not* activated automatically at Docker daemon startup. Rather,
66 
+they are activated only lazily, or on-demand, when they are needed.
67 
+
68 
+## API design
69 
+
70 
+The Plugin API is RPC-style JSON over HTTP, much like webhooks.
71 
+
72 
+Requests flow *from* the Docker daemon *to* the plugin.  So the plugin needs to
73 
+implement an HTTP server and bind this to the UNIX socket mentioned in the
74 
+"plugin discovery" section.
75 
+
76 
+All requests are HTTP `POST` requests.
77 
+
78 
+The API is versioned via an Accept header, which currently is always set to
79 
+`application/vnd.docker.plugins.v1+json`.
80 
+
81 
+## Handshake API
82 
+
83 
+Plugins are activated via the following "handshake" API call.
84 
+
85 
+### /Plugin.Activate
86 
+
87 
+**Request:** empty body
88 
+
89 
+**Response:**
90 
+```
91 
+{
92 
+    "Implements": ["VolumeDriver"]
93 
+}
94 
+```
95 
+
96 
+Responds with a list of Docker subsystems which this plugin implements.
97 
+After activation, the plugin will then be sent events from this subsystem.
98 
+
99 
+## Volume API
100 
+
101 
+If a plugin registers itself as a `VolumeDriver` (see above) then it is
102 
+expected to provide writeable paths on the host filesystem for the Docker
103 
+daemon to provide to containers to consume.
104 
+
105 
+The Docker daemon handles bind-mounting the provided paths into user
106 
+containers.
107 
+
108 
+### /VolumeDriver.Create
109 
+
110 
+**Request**:
111 
+```
112 
+{
113 
+    "Name": "volume_name"
114 
+}
115 
+```
116 
+
117 
+Instruct the plugin that the user wants to create a volume, given a user
118 
+specified volume name.  The plugin does not need to actually manifest the
119 
+volume on the filesystem yet (until Mount is called).
120 
+
121 
+**Response**:
122 
+```
123 
+{
124 
+    "Err": null
125 
+}
126 
+```
127 
+
128 
+Respond with a string error if an error occurred.
129 
+
130 
+### /VolumeDriver.Remove
131 
+
132 
+**Request**:
133 
+```
134 
+{
135 
+    "Name": "volume_name"
136 
+}
137 
+```
138 
+
139 
+Create a volume, given a user specified volume name.
140 
+
141 
+**Response**:
142 
+```
143 
+{
144 
+    "Err": null
145 
+}
146 
+```
147 
+
148 
+Respond with a string error if an error occurred.
149 
+
150 
+### /VolumeDriver.Mount
151 
+
152 
+**Request**:
153 
+```
154 
+{
155 
+    "Name": "volume_name"
156 
+}
157 
+```
158 
+
159 
+Docker requires the plugin to provide a volume, given a user specified volume
160 
+name. This is called once per container start.
161 
+
162 
+**Response**:
163 
+```
164 
+{
165 
+    "Mountpoint": "/path/to/directory/on/host",
166 
+    "Err": null
167 
+}
168 
+```
169 
+
170 
+Respond with the path on the host filesystem where the volume has been made
171 
+available, and/or a string error if an error occurred.
172 
+
173 
+### /VolumeDriver.Path
174 
+
175 
+**Request**:
176 
+```
177 
+{
178 
+    "Name": "volume_name"
179 
+}
180 
+```
181 
+
182 
+Docker needs reminding of the path to the volume on the host.
183 
+
184 
+**Response**:
185 
+```
186 
+{
187 
+    "Mountpoint": "/path/to/directory/on/host",
188 
+    "Err": null
189 
+}
190 
+```
191 
+
192 
+Respond with the path on the host filesystem where the volume has been made
193 
+available, and/or a string error if an error occurred.
194 
+
195 
+### /VolumeDriver.Unmount
196 
+
197 
+**Request**:
198 
+```
199 
+{
200 
+    "Name": "volume_name"
201 
+}
202 
+```
203 
+
204 
+Indication that Docker no longer is using the named volume. This is called once
205 
+per container stop.  Plugin may deduce that it is safe to deprovision it at
206 
+this point.
207 
+
208 
+**Response**:
209 
+```
210 
+{
211 
+    "Err": null
212 
+}
213 
+```
214 
+
215 
+Respond with a string error if an error occurred.
216 
+
217 
+## Plugin retries
218 
+
219 
+Attempts to call a method on a plugin are retried with an exponential backoff
220 
+for up to 30 seconds. This may help when packaging plugins as containers, since
221 
+it gives plugin containers a chance to start up before failing any user
222 
+containers which depend on them.
docs/sources/experimental/plugins.md
History View file @ 8d04868
0 223 
new file mode 100644
... ... 
@@ -0,0 +1,46 @@
0 
+page_title: Experimental feature - Plugins
1 
+page_keywords: experimental, Docker, plugins
2 
+
3 
+# Overview
4 
+
5 
+You can extend the capabilities of the Docker Engine by loading third-party
6 
+plugins.
7 
+
8 
+## Types of plugins
9 
+
10 
+Plugins extend Docker's functionality.  They come in specific types.  For
11 
+example, a [volume plugin](/experimental/plugins_volume) might enable Docker
12 
+volumes to persist across multiple Docker hosts.
13 
+
14 
+Currently Docker supports volume plugins. In the future it will support
15 
+additional plugin types.
16 
+
17 
+## Installing a plugin
18 
+
19 
+Follow the instructions in the plugin's documentation.
20 
+
21 
+## Finding a plugin
22 
+
23 
+The following plugins exist:
24 
+
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
27 
+  databases and other stateful containers and move them around across a cluster
28 
+  of machines.
29 
+
30 
+## Troubleshooting a plugin
31 
+
32 
+If you are having problems with Docker after loading a plugin, ask the authors
33 
+of the plugin for help. The Docker team may not be able to assist you.
34 
+
35 
+## Writing a plugin
36 
+
37 
+If you are interested in writing a plugin for Docker, or seeing how they work
38 
+under the hood, see the [docker plugins reference](/experimental/plugin_api).
39 
+
40 
+# Related GitHub PRs and issues
41 
+
42 
+- [#13222](https://github.com/docker/docker/pull/13222) Plugins plumbing
43 
+
44 
+Send us feedback and comments on [#13419](https://github.com/docker/docker/issues/13419),
45 
+or on the usual Google Groups (docker-user, docker-dev) and IRC channels.
docs/sources/experimental/plugins_volume.md
History View file @ 8d04868
0 46 
new file mode 100644
... ... 
@@ -0,0 +1,43 @@
0 
+page_title: Experimental feature - Volume plugins
1 
+page_keywords: experimental, Docker, plugins, volume
2 
+
3 
+# Overview
4 
+
5 
+Docker volume plugins enable Docker deployments to be integrated with external
6 
+storage systems, such as Amazon EBS, and enable data volumes to persist beyond
7 
+the lifetime of a single Docker host. See the [plugin documentation](/experimental/plugins)
8 
+for more information.
9 
+
10 
+# Command-line changes
11 
+
12 
+This experimental features introduces two changes to the `docker run` command:
13 
+
14 
+- The `--volume-driver` flag is introduced.
15 
+- The `-v` syntax is changed to accept a volume name a first component.
16 
+
17 
+Example:
18 
+
19 
+    $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh
20 
+
21 
+By specifying a volume name in conjunction with a volume driver, volume plugins
22 
+such as [Flocker](https://clusterhq.com/docker-plugin/), once installed, can be
23 
+used to manage volumes external to a single host, such as those on EBS. In this
24 
+example, "volumename" is passed through to the volume plugin as a user-given
25 
+name for the volume which allows the plugin to associate it with an external
26 
+volume beyond the lifetime of a single container or container host. This can be
27 
+used, for example, to move a stateful container from one server to another.
28 
+
29 
+The `volumename` must not begin with a `/`.
30 
+
31 
+# API changes
32 
+
33 
+The container creation endpoint (`/containers/create`) accepts a `VolumeDriver`
34 
+field of type `string` allowing to specify the name of the driver. It's default
35 
+value of `"local"` (the default driver for local volumes).
36 
+
37 
+# Related GitHub PRs and issues
38 
+
39 
+- [#13161](https://github.com/docker/docker/pull/13161) Volume refactor and external volume plugins
40 
+
41 
+Send us feedback and comments on [#13420](https://github.com/docker/docker/issues/13420),
42 
+or on the usual Google Groups (docker-user, docker-dev) and IRC channels.