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).