Docker插件API

Docker插件是进程外扩展，它为Docker引擎添加了功能。

本文档描述了Docker Engine插件API。要查看由Docker Engine管理的插件的信息，请参阅Docker Engine插件系统。

本页面适用于想要开发自己的Docker插件的人员。如果你只是想了解或使用Docker插件，请看这里。

什么插件

插件是与docker守护进程运行在相同或不同主机上的进程，它通过将文件放置在插件发现中描述的插件目录之一中的同一个docker主机上进行注册。

插件具有人类可读的名称，它们是短小的字符串。例如，flocker或weave。

插件可以在容器内部或外部运行。目前建议在容器外部运行它们。

插件发现

每当用户或容器尝试按名称使用插件时，Docker都会通过在插件目录中查找插件来发现插件。

有三种类型的文件可以放在插件目录中。

• .sock 文件是UNIX域套接字。

• .spec文件是包含URL的文本文件，例如unix:///other.sock或tcp://localhost:8080。

• .json 文件是包含插件的完整json规范的文本文件。

具有UNIX域套接字文件的插件必须在相同的docker主机上运行，而具有spec或json文件的插件可以在不同的主机上运行（如果指定了远程URL）。

UNIX域套接字文件必须位于下/run/docker/plugins，而规范的文件可以在位于/etc/docker/plugins或/usr/lib/docker/plugins。

文件的名称（不包括扩展名）确定插件名称。

例如，flocker插件可能会在中创建一个UNIX套接字/run/docker/plugins/flocker.sock。

如果您想将相互隔离的定义隔离起来，您可以将每个插件定义到一个单独的子目录中。例如，您可以在容器内创建flocker套接字/run/docker/plugins/flocker/flocker.sock并仅将其安装/run/docker/plugins/flocker在该flocker容器内。

Docker总是首先搜索unix套接字/run/docker/plugins。它检查规范或json文件/etc/docker/plugins，/usr/lib/docker/plugins如果套接字不存在。目录扫描只要找到具有给定名称的第一个插件定义就会停止。

JSON规范

这是插件的JSON格式：

{  "Name": "plugin-example",  "Addr": "https://example.com/docker/plugin",  "TLSConfig": {    "InsecureSkipVerify": false,    "CAFile": "/usr/shared/docker/certs/example-ca.pem",    "CertFile": "/usr/shared/docker/certs/example-cert.pem",    "KeyFile": "/usr/shared/docker/certs/example-key.pem"  }}

TLSConfig字段是可选的，只有在配置存在时才会验证TLS。

插件生命周期

插件应该在Docker之前启动，并在Docker之后停止。例如，在为支持的平台打包插件时systemd，可以使用systemd依赖关系来管理启动和关闭顺序。

升级插件时，应首先停止Docker守护程序，升级插件，然后再次启动Docker。

插件激活

当插件首次被引用时 - 无论是由用户引用它的名称（例如docker run --volume-driver=foo）还是已经配置为使用插件的容器 -  Docker在插件目录中查找指定的插件，并通过握手激活它。请参阅下面的握手API。

在Docker守护程序启动时插件不会自动激活。相反，它们只在需要时才会被懒惰地或按需地激活。

Systemd套接字激活

插件也可能被套接字激活systemd。官方的插件助手本地支持套接字激活。为了插件被套接字激活，它需要一个service文件和一个socket文件。

service文件（例如/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

socket文件（例如/lib/systemd/system/your-plugin.socket）：

[Unit]Description=Your plugin[Socket]ListenStream=/run/docker/plugins/your-plugin.sock[Install]WantedBy=sockets.target

当Docker守护进程连接到它们正在监听的套接字（例如守护进程第一次使用它们或者其中一个插件意外关闭）时，这将允许插件实际启动。

API设计

插件API是基于HTTP的RPC风格的JSON，非常像webhook。

请求Flow从Docker守护到该插件。所以插件需要实现一个HTTP服务器并将其绑定到“plugin discovery”部分中提到的UNIX套接字。

所有请求都是HTTPPOST请求。

该API通过一个Accept标头进行版本控制，该标头目前始终设置为application/vnd.docker.plugins.v1+json。

Handshake API

通过以下“handshake”API调用来激活插件。

/Plugin.Activate

请求：empty body

回应：

{    "Implements": ["VolumeDriver"]}

响应此插件实现的Docker子系统列表。激活后，插件将从这个子系统发送事件。

可能的值是：

• authz

• NetworkDriver

• VolumeDriver

插件重试

尝试调用插件上的方法将重试指数回退长达30秒。当将插件封装为容器时，这可能会有所帮助，因为它使得插件容器在发生依赖于它们的任何用户容器失败之前有机会启动。

插件助手

为了简化插件开发，我们sdk为Docker /go-plugins-helpers目前支持的各种插件提供了一个插件。