github.com/pwn-term/docker@v0.0.0-20210616085119-6e977cce2565/cli/docs/extend/plugin_api.md (about)

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