github.com/kim0/docker@v0.6.2-0.20161130212042-4addda3f07e7/docs/extend/plugin_api.md (about) 1 --- 2 title: "Plugins API" 3 description: "How to write Docker plugins extensions " 4 keywords: ["API, Usage, plugins, documentation, developer"] 5 --- 6 7 <!-- This file is maintained within the docker/docker Github 8 repository at https://github.com/docker/docker/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # Docker Plugin API 17 18 Docker plugins are out-of-process extensions which add capabilities to the 19 Docker Engine. 20 21 This document describes the Docker Engine plugin API. To view information on 22 plugins managed by Docker Engine currently in experimental status, refer to 23 [Docker Engine plugin system](index.md). 24 25 This page is intended for people who want to develop their own Docker plugin. 26 If you just want to learn about or use Docker plugins, look 27 [here](legacy_plugins.md). 28 29 ## What plugins are 30 31 A plugin is a process running on the same or a different host as the docker daemon, 32 which registers itself by placing a file on the same docker host in one of the plugin 33 directories described in [Plugin discovery](#plugin-discovery). 34 35 Plugins have human-readable names, which are short, lowercase strings. For 36 example, `flocker` or `weave`. 37 38 Plugins can run inside or outside containers. Currently running them outside 39 containers is recommended. 40 41 ## Plugin discovery 42 43 Docker discovers plugins by looking for them in the plugin directory whenever a 44 user or container tries to use one by name. 45 46 There are three types of files which can be put in the plugin directory. 47 48 * `.sock` files are UNIX domain sockets. 49 * `.spec` files are text files containing a URL, such as `unix:///other.sock` or `tcp://localhost:8080`. 50 * `.json` files are text files containing a full json specification for the plugin. 51 52 Plugins with UNIX domain socket files must run on the same docker host, whereas 53 plugins with spec or json files can run on a different host if a remote URL is specified. 54 55 UNIX domain socket files must be located under `/run/docker/plugins`, whereas 56 spec files can be located either under `/etc/docker/plugins` or `/usr/lib/docker/plugins`. 57 58 The name of the file (excluding the extension) determines the plugin name. 59 60 For example, the `flocker` plugin might create a UNIX socket at 61 `/run/docker/plugins/flocker.sock`. 62 63 You can define each plugin into a separated subdirectory if you want to isolate definitions from each other. 64 For example, you can create the `flocker` socket under `/run/docker/plugins/flocker/flocker.sock` and only 65 mount `/run/docker/plugins/flocker` inside the `flocker` container. 66 67 Docker always searches for unix sockets in `/run/docker/plugins` first. It checks for spec or json files under 68 `/etc/docker/plugins` and `/usr/lib/docker/plugins` if the socket doesn't exist. The directory scan stops as 69 soon as it finds the first plugin definition with the given name. 70 71 ### JSON specification 72 73 This is the JSON format for a plugin: 74 75 ```json 76 { 77 "Name": "plugin-example", 78 "Addr": "https://example.com/docker/plugin", 79 "TLSConfig": { 80 "InsecureSkipVerify": false, 81 "CAFile": "/usr/shared/docker/certs/example-ca.pem", 82 "CertFile": "/usr/shared/docker/certs/example-cert.pem", 83 "KeyFile": "/usr/shared/docker/certs/example-key.pem", 84 } 85 } 86 ``` 87 88 The `TLSConfig` field is optional and TLS will only be verified if this configuration is present. 89 90 ## Plugin lifecycle 91 92 Plugins should be started before Docker, and stopped after Docker. For 93 example, when packaging a plugin for a platform which supports `systemd`, you 94 might use [`systemd` dependencies]( 95 http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to 96 manage startup and shutdown order. 97 98 When upgrading a plugin, you should first stop the Docker daemon, upgrade the 99 plugin, then start Docker again. 100 101 ## Plugin activation 102 103 When a plugin is first referred to -- either by a user referring to it by name 104 (e.g. `docker run --volume-driver=foo`) or a container already configured to 105 use a plugin being started -- Docker looks for the named plugin in the plugin 106 directory and activates it with a handshake. See Handshake API below. 107 108 Plugins are *not* activated automatically at Docker daemon startup. Rather, 109 they are activated only lazily, or on-demand, when they are needed. 110 111 ## Systemd socket activation 112 113 Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers) 114 natively supports socket activation. In order for a plugin to be socket activated it needs 115 a `service` file and a `socket` file. 116 117 The `service` file (for example `/lib/systemd/system/your-plugin.service`): 118 119 ``` 120 [Unit] 121 Description=Your plugin 122 Before=docker.service 123 After=network.target your-plugin.socket 124 Requires=your-plugin.socket docker.service 125 126 [Service] 127 ExecStart=/usr/lib/docker/your-plugin 128 129 [Install] 130 WantedBy=multi-user.target 131 ``` 132 The `socket` file (for example `/lib/systemd/system/your-plugin.socket`): 133 134 ``` 135 [Unit] 136 Description=Your plugin 137 138 [Socket] 139 ListenStream=/run/docker/plugins/your-plugin.sock 140 141 [Install] 142 WantedBy=sockets.target 143 ``` 144 145 This will allow plugins to be actually started when the Docker daemon connects to 146 the sockets they're listening on (for instance the first time the daemon uses them 147 or if one of the plugin goes down accidentally). 148 149 ## API design 150 151 The Plugin API is RPC-style JSON over HTTP, much like webhooks. 152 153 Requests flow *from* the Docker daemon *to* the plugin. So the plugin needs to 154 implement an HTTP server and bind this to the UNIX socket mentioned in the 155 "plugin discovery" section. 156 157 All requests are HTTP `POST` requests. 158 159 The API is versioned via an Accept header, which currently is always set to 160 `application/vnd.docker.plugins.v1+json`. 161 162 ## Handshake API 163 164 Plugins are activated via the following "handshake" API call. 165 166 ### /Plugin.Activate 167 168 **Request:** empty body 169 170 **Response:** 171 ``` 172 { 173 "Implements": ["VolumeDriver"] 174 } 175 ``` 176 177 Responds with a list of Docker subsystems which this plugin implements. 178 After activation, the plugin will then be sent events from this subsystem. 179 180 Possible values are: 181 182 * [`authz`](plugins_authorization.md) 183 * [`NetworkDriver`](plugins_network.md) 184 * [`VolumeDriver`](plugins_volume.md) 185 186 187 ## Plugin retries 188 189 Attempts to call a method on a plugin are retried with an exponential backoff 190 for up to 30 seconds. This may help when packaging plugins as containers, since 191 it gives plugin containers a chance to start up before failing any user 192 containers which depend on them. 193 194 ## Plugins helpers 195 196 To ease plugins development, we're providing an `sdk` for each kind of plugins 197 currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).