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