Docker插件API

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

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

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

什么是插件

插件是与docker守护程序在相同或不同主机上运行的进程，该进程通过将文件放置在Plugin Discovery中所述插件目录之一中的相同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。它检查下是否存在spec或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。官方的插件助手本身就支持套接字激活。为了使插件通过套接字激活，它需要一个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，非常类似于webhooks。

请求从Docker守护程序到插件的流。因此，该插件需要实现HTTP服务器，并将其绑定到“插件发现”部分中提到的UNIX套接字。

所有请求都是HTTPPOST请求。

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

握手API

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

/Plugin.Activate

要求：空体

回复：

{
    "Implements": ["VolumeDriver"]
}

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

可能的值为：

插件重试

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

插件助手

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

API，用法，插件，文档，开发人员