new repository

1 files changed, 43 insertions, 0 deletions

diff --git a/devdocs/docker/engine%2Fextend%2Fplugin_api%2Findex.html b/devdocs/docker/engine%2Fextend%2Fplugin_api%2Findex.html
new file mode 100644
index 00000000..707ab33a
--- /dev/null
+++ b/devdocs/docker/engine%2Fextend%2Fplugin_api%2Findex.html
@@ -0,0 +1,43 @@
+ <h1 id="docker-plugin-api">Docker Plugin API</h1> <p>Docker plugins are out-of-process extensions which add capabilities to the Docker Engine.</p> <p>This document describes the Docker Engine plugin API. To view information on plugins managed by Docker Engine, refer to <a href="../index">Docker Engine plugin system</a>.</p> <p>This page is intended for people who want to develop their own Docker plugin. If you just want to learn about or use Docker plugins, look <a href="../legacy_plugins/index">here</a>.</p> <h2 id="what-plugins-are">What plugins are</h2> <p>A plugin is a process running on the same or a different host as the docker daemon, which registers itself by placing a file on the same docker host in one of the plugin directories described in <a href="#plugin-discovery">Plugin discovery</a>.</p> <p>Plugins have human-readable names, which are short, lowercase strings. For example, <code class="language-plaintext highlighter-rouge">flocker</code> or <code class="language-plaintext highlighter-rouge">weave</code>.</p> <p>Plugins can run inside or outside containers. Currently running them outside containers is recommended.</p> <h2 id="plugin-discovery">Plugin discovery</h2> <p>Docker discovers plugins by looking for them in the plugin directory whenever a user or container tries to use one by name.</p> <p>There are three types of files which can be put in the plugin directory.</p> <ul> <li>
+<code class="language-plaintext highlighter-rouge">.sock</code> files are UNIX domain sockets.</li> <li>
+<code class="language-plaintext highlighter-rouge">.spec</code> files are text files containing a URL, such as <code class="language-plaintext highlighter-rouge">unix:///other.sock</code> or <code class="language-plaintext highlighter-rouge">tcp://localhost:8080</code>.</li> <li>
+<code class="language-plaintext highlighter-rouge">.json</code> files are text files containing a full json specification for the plugin.</li> </ul> <p>Plugins with UNIX domain socket files must run on the same docker host, whereas plugins with spec or json files can run on a different host if a remote URL is specified.</p> <p>UNIX domain socket files must be located under <code class="language-plaintext highlighter-rouge">/run/docker/plugins</code>, whereas spec files can be located either under <code class="language-plaintext highlighter-rouge">/etc/docker/plugins</code> or <code class="language-plaintext highlighter-rouge">/usr/lib/docker/plugins</code>.</p> <p>The name of the file (excluding the extension) determines the plugin name.</p> <p>For example, the <code class="language-plaintext highlighter-rouge">flocker</code> plugin might create a UNIX socket at <code class="language-plaintext highlighter-rouge">/run/docker/plugins/flocker.sock</code>.</p> <p>You can define each plugin into a separated subdirectory if you want to isolate definitions from each other. For example, you can create the <code class="language-plaintext highlighter-rouge">flocker</code> socket under <code class="language-plaintext highlighter-rouge">/run/docker/plugins/flocker/flocker.sock</code> and only mount <code class="language-plaintext highlighter-rouge">/run/docker/plugins/flocker</code> inside the <code class="language-plaintext highlighter-rouge">flocker</code> container.</p> <p>Docker always searches for unix sockets in <code class="language-plaintext highlighter-rouge">/run/docker/plugins</code> first. It checks for spec or json files under <code class="language-plaintext highlighter-rouge">/etc/docker/plugins</code> and <code class="language-plaintext highlighter-rouge">/usr/lib/docker/plugins</code> if the socket doesn’t exist. The directory scan stops as soon as it finds the first plugin definition with the given name.</p> <h3 id="json-specification">JSON specification</h3> <p>This is the JSON format for a plugin:</p> <div class="highlight"><pre class="highlight" data-language="">{
+  "Name": "plugin-example",
+  "Addr": "https://example.com/docker/plugin",
+  "TLSConfig": {
+    "InsecureSkipVerify": false,
+    "CAFile": "/usr/shared/docker/certs/example-ca.pem",
+    "CertFile": "/usr/shared/docker/certs/example-cert.pem",
+    "KeyFile": "/usr/shared/docker/certs/example-key.pem"
+  }
+}
+</pre></div> <p>The <code class="language-plaintext highlighter-rouge">TLSConfig</code> field is optional and TLS will only be verified if this configuration is present.</p> <h2 id="plugin-lifecycle">Plugin lifecycle</h2> <p>Plugins should be started before Docker, and stopped after Docker. For example, when packaging a plugin for a platform which supports <code class="language-plaintext highlighter-rouge">systemd</code>, you might use <a href="https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before="><code class="language-plaintext highlighter-rouge">systemd</code> dependencies</a> to manage startup and shutdown order.</p> <p>When upgrading a plugin, you should first stop the Docker daemon, upgrade the plugin, then start Docker again.</p> <h2 id="plugin-activation">Plugin activation</h2> <p>When a plugin is first referred to -- either by a user referring to it by name (e.g. <code class="language-plaintext highlighter-rouge">docker run --volume-driver=foo</code>) or a container already configured to use a plugin being started -- Docker looks for the named plugin in the plugin directory and activates it with a handshake. See Handshake API below.</p> <p>Plugins are <em>not</em> activated automatically at Docker daemon startup. Rather, they are activated only lazily, or on-demand, when they are needed.</p> <h2 id="systemd-socket-activation">Systemd socket activation</h2> <p>Plugins may also be socket activated by <code class="language-plaintext highlighter-rouge">systemd</code>. The official <a href="https://github.com/docker/go-plugins-helpers">Plugins helpers</a> natively supports socket activation. In order for a plugin to be socket activated it needs a <code class="language-plaintext highlighter-rouge">service</code> file and a <code class="language-plaintext highlighter-rouge">socket</code> file.</p> <p>The <code class="language-plaintext highlighter-rouge">service</code> file (for example <code class="language-plaintext highlighter-rouge">/lib/systemd/system/your-plugin.service</code>):</p> <div class="highlight"><pre class="highlight" data-language="">[Unit]
+Description=Your plugin
+Before=docker.service
+After=network.target your-plugin.socket
+Requires=your-plugin.socket docker.service
+
+[Service]
+ExecStart=/usr/lib/docker/your-plugin
+
+[Install]
+WantedBy=multi-user.target
+</pre></div> <p>The <code class="language-plaintext highlighter-rouge">socket</code> file (for example <code class="language-plaintext highlighter-rouge">/lib/systemd/system/your-plugin.socket</code>):</p> <div class="highlight"><pre class="highlight" data-language="">[Unit]
+Description=Your plugin
+
+[Socket]
+ListenStream=/run/docker/plugins/your-plugin.sock
+
+[Install]
+WantedBy=sockets.target
+</pre></div> <p>This will allow plugins to be actually started when the Docker daemon connects to the sockets they’re listening on (for instance the first time the daemon uses them or if one of the plugin goes down accidentally).</p> <h2 id="api-design">API design</h2> <p>The Plugin API is RPC-style JSON over HTTP, much like webhooks.</p> <p>Requests flow <em>from</em> the Docker daemon <em>to</em> the plugin. So the plugin needs to implement an HTTP server and bind this to the UNIX socket mentioned in the “plugin discovery” section.</p> <p>All requests are HTTP <code class="language-plaintext highlighter-rouge">POST</code> requests.</p> <p>The API is versioned via an Accept header, which currently is always set to <code class="language-plaintext highlighter-rouge">application/vnd.docker.plugins.v1+json</code>.</p> <h2 id="handshake-api">Handshake API</h2> <p>Plugins are activated via the following “handshake” API call.</p> <h3 id="pluginactivate">/Plugin.Activate</h3> <p><strong>Request:</strong> empty body</p> <p><strong>Response:</strong></p> <div class="highlight"><pre class="highlight" data-language="">{
+    "Implements": ["VolumeDriver"]
+}
+</pre></div> <p>Responds with a list of Docker subsystems which this plugin implements. After activation, the plugin will then be sent events from this subsystem.</p> <p>Possible values are:</p> <ul> <li><a href="../plugins_authorization/index"><code class="language-plaintext highlighter-rouge">authz</code></a></li> <li><a href="../plugins_network/index"><code class="language-plaintext highlighter-rouge">NetworkDriver</code></a></li> <li><a href="../plugins_volume/index"><code class="language-plaintext highlighter-rouge">VolumeDriver</code></a></li> </ul> <h2 id="plugin-retries">Plugin retries</h2> <p>Attempts to call a method on a plugin are retried with an exponential backoff for up to 30 seconds. This may help when packaging plugins as containers, since it gives plugin containers a chance to start up before failing any user containers which depend on them.</p> <h2 id="plugins-helpers">Plugins helpers</h2> <p>To ease plugins development, we’re providing an <code class="language-plaintext highlighter-rouge">sdk</code> for each kind of plugins currently supported by Docker at <a href="https://github.com/docker/go-plugins-helpers">docker/go-plugins-helpers</a>.</p> 
+<p><a href="https://docs.docker.com/search/?q=API">API</a>, <a href="https://docs.docker.com/search/?q=Usage">Usage</a>, <a href="https://docs.docker.com/search/?q=plugins">plugins</a>, <a href="https://docs.docker.com/search/?q=documentation">documentation</a>, <a href="https://docs.docker.com/search/?q=developer">developer</a></p>
+<div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
+    <a href="https://docs.docker.com/engine/extend/plugin_api/" class="_attribution-link">https://docs.docker.com/engine/extend/plugin_api/</a>
+  </p>
+</div>