Docker 插件 API

目录

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

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

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

什么是插件

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

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

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

插件发现

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

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

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

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

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

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

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

如果您想将定义彼此隔离，可以将每个插件定义到单独的子目录中。例如，您可以在 /run/docker/plugins/flocker/flocker.sock 下创建 flocker 套接字，并且只在 flocker 容器内挂载 /run/docker/plugins/flocker。

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

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 是 RPC 风格的 JSON over HTTP，很像 Webhook。

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

所有请求都是 HTTP POST 请求。

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

握手 API

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

/Plugin.Activate

请求：空正文

响应

{
    "Implements": ["VolumeDriver"]
}

响应此插件实现的 Docker 子系统列表。激活后，插件将收到来自此子系统的事件。

可能的值有

插件重试

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

插件助手

为了简化插件开发，我们为 Docker 目前支持的每种插件类型提供了 sdk，地址是docker/go-plugins-helpers。

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.