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