Merge pull request #21043 from runcom/plugin-sdk

docs: extend: plugins: mention the sdk + systemd socket activation

docs/extend/index.md

@@ -18,5 +18,5 @@ Currently, you can extend Docker Engine by adding a plugin. This section contain
 * [Understand Docker plugins](plugins.md)
 * [Write a volume plugin](plugins_volume.md)
 * [Write a network plugin](plugins_network.md)
-* [Write an authorization plugin](authorization.md)
+* [Write an authorization plugin](plugins_authorization.md)
 * [Docker plugin API](plugin_api.md)

docs/extend/plugin_api.md

@@ -96,6 +96,43 @@ directory and activates it with a handshake. See Handshake API below.
 Plugins are *not* activated automatically at Docker daemon startup. Rather,
 they are activated only lazily, or on-demand, when they are needed.
 
+## Systemd socket activation
+
+Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers)
+natively supports socket activation. In order for a plugin to be socket activated it needs
+a `service` file and a `socket` file.
+
+The `service` file (for example `/lib/systemd/system/your-plugin.service`):
+
+```
+[Unit]
+Description=Your plugin
+Before=docker.service
+After=network.target your-plugin.socket
+Requires=your-plugin.socket docker.service
+
+[Service]
+ExecStart=/usr/lib/docker/your-plugin
+
+[Install]
+WantedBy=multi-user.target
+```
+The `socket` file (for example `/lib/systemd/system/your-plugin.socket`):
+```
+[Unit]
+Description=Your plugin
+
+[Socket]
+ListenStream=/run/docker/plugins/your-plugin.sock
+
+[Install]
+WantedBy=sockets.target
+```
+
+This will allow plugins to be actually started when the Docker daemon connects to
+the sockets they're listening on (for instance the first time the daemon uses them
+or if one of the plugin goes down accidentally).
+
 ## API design
 
 The Plugin API is RPC-style JSON over HTTP, much like webhooks.
@@ -128,7 +165,7 @@ Responds with a list of Docker subsystems which this plugin implements.
 After activation, the plugin will then be sent events from this subsystem.
 
 Possible values are:
- - [`authz`](authorization.md)
+ - [`authz`](plugins_authorization.md)
  - [`NetworkDriver`](plugins_network.md)
  - [`VolumeDriver`](plugins_volume.md)
 
@@ -139,3 +176,8 @@ Attempts to call a method on a plugin are retried with an exponential backoff
 for up to 30 seconds. This may help when packaging plugins as containers, since
 it gives plugin containers a chance to start up before failing any user
 containers which depend on them.
+
+## Plugins helpers
+
+To ease plugins development, we're providing an `sdk` for each kind of plugins
+currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).

docs/extend/plugins_authorization.md

@@ -3,6 +3,7 @@
 title = "Access authorization plugin"
 description = "How to create authorization plugins to manage access control to your Docker daemon."
 keywords = ["security, authorization, authentication, docker, documentation, plugin, extend"]
+aliases = ["/engine/extend/authorization/"]
 [menu.main]
 parent = "engine_extend"
 weight = -1

docs/reference/commandline/daemon.md

@@ -644,7 +644,7 @@ multiple plugins installed, at least one must allow the request for it to
 complete.
 
 For information about how to create an authorization plugin, see [authorization
-plugin](../../extend/authorization.md) section in the Docker extend section of this documentation.
+plugin](../../extend/plugins_authorization.md) section in the Docker extend section of this documentation.
 
 
 ## Daemon user namespace options

man/docker-daemon.8.md

@@ -521,7 +521,7 @@ multiple plugins installed, at least one must allow the request for it to
 complete.
 
 For information about how to create an authorization plugin, see [authorization
-plugin](https://docs.docker.com/engine/extend/authorization.md) section in the
+plugin](https://docs.docker.com/engine/extend/plugins_authorization.md) section in the
 Docker extend section of this documentation.