github.com/khulnasoft/cli@v0.0.0-20240402070845-01bcad7beefa/docs/extend/plugin_api.md (about)

     1  ---
     2  title: Docker Plugin API
     3  description: "How to write Docker plugins extensions "
     4  keywords: "API, Usage, plugins, documentation, developer"
     5  ---
     6  
     7  Docker plugins are out-of-process extensions which add capabilities to the
     8  Docker Engine.
     9  
    10  This document describes the Docker Engine plugin API. To view information on
    11  plugins managed by Docker Engine, refer to [Docker Engine plugin system](index.md).
    12  
    13  This page is intended for people who want to develop their own Docker plugin.
    14  If you just want to learn about or use Docker plugins, look
    15  [here](legacy_plugins.md).
    16  
    17  ## What plugins are
    18  
    19  A plugin is a process running on the same or a different host as the Docker daemon,
    20  which registers itself by placing a file on the daemon host in one of the plugin
    21  directories described in [Plugin discovery](#plugin-discovery).
    22  
    23  Plugins have human-readable names, which are short, lowercase strings. For
    24  example, `flocker` or `weave`.
    25  
    26  Plugins can run inside or outside containers. Currently running them outside
    27  containers is recommended.
    28  
    29  ## Plugin discovery
    30  
    31  Docker discovers plugins by looking for them in the plugin directory whenever a
    32  user or container tries to use one by name.
    33  
    34  There are three types of files which can be put in the plugin directory.
    35  
    36  * `.sock` files are Unix domain sockets.
    37  * `.spec` files are text files containing a URL, such as `unix:///other.sock` or `tcp://localhost:8080`.
    38  * `.json` files are text files containing a full json specification for the plugin.
    39  
    40  Plugins with Unix domain socket files must run on the same host as the Docker daemon.
    41  Plugins with `.spec` or `.json` files can run on a different host if you specify a remote URL.
    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  https://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  ## Systemd socket activation
   100  
   101  Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers)
   102  natively supports socket activation. In order for a plugin to be socket activated it needs
   103  a `service` file and a `socket` file.
   104  
   105  The `service` file (for example `/lib/systemd/system/your-plugin.service`):
   106  
   107  ```systemd
   108  [Unit]
   109  Description=Your plugin
   110  Before=docker.service
   111  After=network.target your-plugin.socket
   112  Requires=your-plugin.socket docker.service
   113  
   114  [Service]
   115  ExecStart=/usr/lib/docker/your-plugin
   116  
   117  [Install]
   118  WantedBy=multi-user.target
   119  ```
   120  
   121  The `socket` file (for example `/lib/systemd/system/your-plugin.socket`):
   122  
   123  ```systemd
   124  [Unit]
   125  Description=Your plugin
   126  
   127  [Socket]
   128  ListenStream=/run/docker/plugins/your-plugin.sock
   129  
   130  [Install]
   131  WantedBy=sockets.target
   132  ```
   133  
   134  This will allow plugins to be actually started when the Docker daemon connects to
   135  the sockets they're listening on (for instance the first time the daemon uses them
   136  or if one of the plugin goes down accidentally).
   137  
   138  ## API design
   139  
   140  The Plugin API is RPC-style JSON over HTTP, much like webhooks.
   141  
   142  Requests flow from the Docker daemon to the plugin. The plugin needs to
   143  implement an HTTP server and bind this to the Unix socket mentioned in the
   144  "plugin discovery" section.
   145  
   146  All requests are HTTP `POST` requests.
   147  
   148  The API is versioned via an Accept header, which currently is always set to
   149  `application/vnd.docker.plugins.v1+json`.
   150  
   151  ## Handshake API
   152  
   153  Plugins are activated via the following "handshake" API call.
   154  
   155  ### /Plugin.Activate
   156  
   157  Request: empty body
   158  
   159  Response:
   160  
   161  ```json
   162  {
   163      "Implements": ["VolumeDriver"]
   164  }
   165  ```
   166  
   167  Responds with a list of Docker subsystems which this plugin implements.
   168  After activation, the plugin will then be sent events from this subsystem.
   169  
   170  Possible values are:
   171  
   172  * [`authz`](plugins_authorization.md)
   173  * [`NetworkDriver`](plugins_network.md)
   174  * [`VolumeDriver`](plugins_volume.md)
   175  
   176  ## Plugin retries
   177  
   178  Attempts to call a method on a plugin are retried with an exponential backoff
   179  for up to 30 seconds. This may help when packaging plugins as containers, since
   180  it gives plugin containers a chance to start up before failing any user
   181  containers which depend on them.
   182  
   183  ## Plugins helpers
   184  
   185  To ease plugins development, we're providing an `sdk` for each kind of plugins
   186  currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).