Docker 插件 API

Docker 插件是进程外扩展，可向 Docker 引擎。

本文档介绍了 Docker Engine 插件 API。要查看由 Docker Engine 管理的插件，请参考 Docker Engine 插件系统。

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

什么是插件

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

插件具有人类可读的名称，这些名称是简短的小写字符串。为例flocker或weave.

插件可以在容器内部或外部运行。目前在外面运行 containers 的 API API 的

插件发现

Docker 通过在插件目录中查找插件来发现插件，每当有 user 或 container 尝试按名称使用一个 NAME。

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

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

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

Unix 域套接字文件必须位于/run/docker/plugins而 spec 文件可以位于/etc/docker/plugins或/usr/lib/docker/plugins.

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

例如，flockerplugin 可能会在/run/docker/plugins/flocker.sock.

如果要将定义彼此隔离，可以将每个插件定义到一个单独的子目录中。例如，您可以创建flockersocket 下/run/docker/plugins/flocker/flocker.sock并且只有安装/run/docker/plugins/flocker在flocker容器。

Docker 总是在/run/docker/plugins第一。它会在/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.官方的 Plugins 帮助程序本身就支持 socket 激活。为了使插件被套接字激活，它需要一个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 非常相似。

请求从 Docker 守护程序流向插件。插件需要实现一个 HTTP 服务器，并将其绑定到 “plugin discovery” 部分。

所有请求都是 HTTPPOST请求。

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

握手 API

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

/Plugin.Activate

请求：空体

响应：

{
    "Implements": ["VolumeDriver"]
}

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

可能的值为：

插件重试

尝试在插件上调用方法时，将使用指数退避重试最多 30 秒。这在将插件打包为容器时可能会有所帮助，因为它为插件容器提供了在失败任何用户之前启动的机会 containers 的 shell 来执行。

插件帮助程序

为了简化插件开发，我们提供了一个sdk对于每种插件 Docker 目前在 docker/go-plugins-helpers 上支持。