Docker 插件 API

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

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

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

什么是插件

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

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

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

插件发现

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

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

.sock文件是 Unix 域套接字。
.spec文件是包含 URL 的文本文件，例如unix:///other.sock或tcp://localhost:8080。
.jsonfiles 是包含插件完整 json 规范的文本文件。

具有 Unix 域套接字文件的插件必须与 Docker 守护进程在同一主机上运行。如果指定远程 URL，带有.spec或文件的插件.json可以在不同的主机上运行。

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。

[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，非常类似于 Webhooks。

请求从 Docker 守护进程流向插件。该插件需要实现一个 HTTP 服务器并将其绑定到“插件发现”部分中提到的 Unix 套接字。

所有请求都是HTTPPOST请求。

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

握手API

插件通过以下“握手”API 调用激活。

/插件.激活

请求：空体

回复：

{
    "Implements": ["VolumeDriver"]
}

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

可能的值为：

插件重试

尝试调用插件上的方法会以指数退避方式重试，最长可达 30 秒。这在将插件打包为容器时可能会有所帮助，因为它使插件容器有机会在依赖于它们的任何用户容器失败之前启动。

插件助手

为了简化插件开发，我们在docker/go-plugins-helperssdk中为 Docker 当前支持的每种插件提供了一个版本。