github.com/a4a881d4/docker@v1.9.0-rc2/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 = "mn_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 docker host as the docker daemon,
    24  which registers itself by placing a file in one of the plugin directories described in [Plugin discovery](#plugin-discovery).
    25  
    26  Plugins have human-readable names, which are short, lowercase strings. For
    27  example, `flocker` or `weave`.
    28  
    29  Plugins can run inside or outside containers. Currently running them outside
    30  containers is recommended.
    31  
    32  ## Plugin discovery
    33  
    34  Docker discovers plugins by looking for them in the plugin directory whenever a
    35  user or container tries to use one by name.
    36  
    37  There are three types of files which can be put in the plugin directory.
    38  
    39  * `.sock` files are UNIX domain sockets.
    40  * `.spec` files are text files containing a URL, such as `unix:///other.sock`.
    41  * `.json` files are text files containing a full json specification for the plugin.
    42  
    43  UNIX domain socket files must be located under `/run/docker/plugins`, whereas
    44  spec files can be located either under `/etc/docker/plugins` or `/usr/lib/docker/plugins`.
    45  
    46  The name of the file (excluding the extension) determines the plugin name.
    47  
    48  For example, the `flocker` plugin might create a UNIX socket at
    49  `/run/docker/plugins/flocker.sock`.
    50  
    51  You can define each plugin into a separated subdirectory if you want to isolate definitions from each other.
    52  For example, you can create the `flocker` socket under `/run/docker/plugins/flocker/flocker.sock` and only
    53  mount `/run/docker/plugins/flocker` inside the `flocker` container.
    54  
    55  Docker always searches for unix sockets in `/run/docker/plugins` first. It checks for spec or json files under
    56  `/etc/docker/plugins` and `/usr/lib/docker/plugins` if the socket doesn't exist. The directory scan stops as
    57  soon as it finds the first plugin definition with the given name.
    58  
    59  ### JSON specification
    60  
    61  This is the JSON format for a plugin:
    62  
    63  ```json
    64  {
    65    "Name": "plugin-example",
    66    "Addr": "https://example.com/docker/plugin",
    67    "TLSConfig": {
    68      "InsecureSkipVerify": false,
    69      "CAFile": "/usr/shared/docker/certs/example-ca.pem",
    70      "CertFile": "/usr/shared/docker/certs/example-cert.pem",
    71      "KeyFile": "/usr/shared/docker/certs/example-key.pem",
    72    }
    73  }
    74  ```
    75  
    76  The `TLSConfig` field is optional and TLS will only be verified if this configuration is present.
    77  
    78  ## Plugin lifecycle
    79  
    80  Plugins should be started before Docker, and stopped after Docker.  For
    81  example, when packaging a plugin for a platform which supports `systemd`, you
    82  might use [`systemd` dependencies](
    83  http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to
    84  manage startup and shutdown order.
    85  
    86  When upgrading a plugin, you should first stop the Docker daemon, upgrade the
    87  plugin, then start Docker again.
    88  
    89  ## Plugin activation
    90  
    91  When a plugin is first referred to -- either by a user referring to it by name
    92  (e.g.  `docker run --volume-driver=foo`) or a container already configured to
    93  use a plugin being started -- Docker looks for the named plugin in the plugin
    94  directory and activates it with a handshake. See Handshake API below.
    95  
    96  Plugins are *not* activated automatically at Docker daemon startup. Rather,
    97  they are activated only lazily, or on-demand, when they are needed.
    98  
    99  ## API design
   100  
   101  The Plugin API is RPC-style JSON over HTTP, much like webhooks.
   102  
   103  Requests flow *from* the Docker daemon *to* the plugin.  So the plugin needs to
   104  implement an HTTP server and bind this to the UNIX socket mentioned in the
   105  "plugin discovery" section.
   106  
   107  All requests are HTTP `POST` requests.
   108  
   109  The API is versioned via an Accept header, which currently is always set to
   110  `application/vnd.docker.plugins.v1+json`.
   111  
   112  ## Handshake API
   113  
   114  Plugins are activated via the following "handshake" API call.
   115  
   116  ### /Plugin.Activate
   117  
   118  **Request:** empty body
   119  
   120  **Response:**
   121  ```
   122  {
   123      "Implements": ["VolumeDriver"]
   124  }
   125  ```
   126  
   127  Responds with a list of Docker subsystems which this plugin implements.
   128  After activation, the plugin will then be sent events from this subsystem.
   129  
   130  ## Plugin retries
   131  
   132  Attempts to call a method on a plugin are retried with an exponential backoff
   133  for up to 30 seconds. This may help when packaging plugins as containers, since
   134  it gives plugin containers a chance to start up before failing any user
   135  containers which depend on them.