github.com/jogo/docker@v1.7.0-rc1/docs/sources/experimental/plugin_api.md (about) 1 page_title: Plugin API documentation 2 page_description: Documentation for writing a Docker plugin. 3 page_keywords: docker, plugins, api, extensions 4 5 # Experimental: Docker Plugin API 6 7 Docker plugins are out-of-process extensions which add capabilities to the 8 Docker Engine. 9 10 This page is intended for people who want to develop their own Docker plugin. 11 If you just want to learn about or use Docker plugins, look 12 [here](/userguide/plugins). 13 14 This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](experimental.md). 15 16 ## What plugins are 17 18 A plugin is a process running on the same docker host as the docker daemon, 19 which registers itself by placing a file in `/usr/share/docker/plugins` (the 20 "plugin directory"). 21 22 Plugins have human-readable names, which are short, lowercase strings. For 23 example, `flocker` or `weave`. 24 25 Plugins can run inside or outside containers. Currently running them outside 26 containers is recommended. 27 28 ## Plugin discovery 29 30 Docker discovers plugins by looking for them in the plugin directory whenever a 31 user or container tries to use one by name. 32 33 There are two types of files which can be put in the plugin directory. 34 35 * `.sock` files are UNIX domain sockets. 36 * `.spec` files are text files containing a URL, such as `unix:///other.sock`. 37 38 The name of the file (excluding the extension) determines the plugin name. 39 40 For example, the `flocker` plugin might create a UNIX socket at 41 `/usr/share/docker/plugins/flocker.sock`. 42 43 Plugins must be run locally on the same machine as the Docker daemon. UNIX 44 domain sockets are strongly encouraged for security reasons. 45 46 ## Plugin lifecycle 47 48 Plugins should be started before Docker, and stopped after Docker. For 49 example, when packaging a plugin for a platform which supports `systemd`, you 50 might use [`systemd` dependencies]( 51 http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to 52 manage startup and shutdown order. 53 54 When upgrading a plugin, you should first stop the Docker daemon, upgrade the 55 plugin, then start Docker again. 56 57 If a plugin is packaged as a container, this may cause issues. Plugins as 58 containers are currently considered experimental due to these shutdown/startup 59 ordering issues. These issues are mitigated by plugin retries (see below). 60 61 ## Plugin activation 62 63 When a plugin is first referred to -- either by a user referring to it by name 64 (e.g. `docker run --volume-driver=foo`) or a container already configured to 65 use a plugin being started -- Docker looks for the named plugin in the plugin 66 directory and activates it with a handshake. See Handshake API below. 67 68 Plugins are *not* activated automatically at Docker daemon startup. Rather, 69 they are activated only lazily, or on-demand, when they are needed. 70 71 ## API design 72 73 The Plugin API is RPC-style JSON over HTTP, much like webhooks. 74 75 Requests flow *from* the Docker daemon *to* the plugin. So the plugin needs to 76 implement an HTTP server and bind this to the UNIX socket mentioned in the 77 "plugin discovery" section. 78 79 All requests are HTTP `POST` requests. 80 81 The API is versioned via an Accept header, which currently is always set to 82 `application/vnd.docker.plugins.v1+json`. 83 84 ## Handshake API 85 86 Plugins are activated via the following "handshake" API call. 87 88 ### /Plugin.Activate 89 90 **Request:** empty body 91 92 **Response:** 93 ``` 94 { 95 "Implements": ["VolumeDriver"] 96 } 97 ``` 98 99 Responds with a list of Docker subsystems which this plugin implements. 100 After activation, the plugin will then be sent events from this subsystem. 101 102 ## Volume API 103 104 If a plugin registers itself as a `VolumeDriver` (see above) then it is 105 expected to provide writeable paths on the host filesystem for the Docker 106 daemon to provide to containers to consume. 107 108 The Docker daemon handles bind-mounting the provided paths into user 109 containers. 110 111 ### /VolumeDriver.Create 112 113 **Request**: 114 ``` 115 { 116 "Name": "volume_name" 117 } 118 ``` 119 120 Instruct the plugin that the user wants to create a volume, given a user 121 specified volume name. The plugin does not need to actually manifest the 122 volume on the filesystem yet (until Mount is called). 123 124 **Response**: 125 ``` 126 { 127 "Err": null 128 } 129 ``` 130 131 Respond with a string error if an error occurred. 132 133 ### /VolumeDriver.Remove 134 135 **Request**: 136 ``` 137 { 138 "Name": "volume_name" 139 } 140 ``` 141 142 Create a volume, given a user specified volume name. 143 144 **Response**: 145 ``` 146 { 147 "Err": null 148 } 149 ``` 150 151 Respond with a string error if an error occurred. 152 153 ### /VolumeDriver.Mount 154 155 **Request**: 156 ``` 157 { 158 "Name": "volume_name" 159 } 160 ``` 161 162 Docker requires the plugin to provide a volume, given a user specified volume 163 name. This is called once per container start. 164 165 **Response**: 166 ``` 167 { 168 "Mountpoint": "/path/to/directory/on/host", 169 "Err": null 170 } 171 ``` 172 173 Respond with the path on the host filesystem where the volume has been made 174 available, and/or a string error if an error occurred. 175 176 ### /VolumeDriver.Path 177 178 **Request**: 179 ``` 180 { 181 "Name": "volume_name" 182 } 183 ``` 184 185 Docker needs reminding of the path to the volume on the host. 186 187 **Response**: 188 ``` 189 { 190 "Mountpoint": "/path/to/directory/on/host", 191 "Err": null 192 } 193 ``` 194 195 Respond with the path on the host filesystem where the volume has been made 196 available, and/or a string error if an error occurred. 197 198 ### /VolumeDriver.Unmount 199 200 **Request**: 201 ``` 202 { 203 "Name": "volume_name" 204 } 205 ``` 206 207 Indication that Docker no longer is using the named volume. This is called once 208 per container stop. Plugin may deduce that it is safe to deprovision it at 209 this point. 210 211 **Response**: 212 ``` 213 { 214 "Err": null 215 } 216 ``` 217 218 Respond with a string error if an error occurred. 219 220 ## Plugin retries 221 222 Attempts to call a method on a plugin are retried with an exponential backoff 223 for up to 30 seconds. This may help when packaging plugins as containers, since 224 it gives plugin containers a chance to start up before failing any user 225 containers which depend on them.