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