Docker 外掛 API

Docker 外掛程式是流程外 (out-of-process) 的擴充功能，為 Docker Engine 增加新功能。

本文件說明 Docker Engine 外掛程式 API。若要查看 Docker Engine 所管理的外掛程式相關資訊，請參閱 Docker Engine 外掛程式系統。

本頁旨在為想要開發自訂 Docker 外掛程式的開發者提供資訊。如果您只是想了解或使用 Docker 外掛程式，請參閱此處。

什麼是外掛程式

外掛程式是一個執行於 Docker daemon 所在主機或遠端主機上的行程，它透過在 daemon 主機的其中一個外掛程式目錄中放置檔案來進行註冊，詳情請見外掛程式探索。

外掛程式有名為「人眼可讀」的名稱，通常是簡短的小寫字串。例如：flocker 或 weave。

外掛程式可以執行於容器內或容器外。目前建議將其執行於容器外。

外掛程式探索

當使用者或容器嘗試依名稱使用某個外掛程式時，Docker 會在外掛程式目錄中搜尋該外掛程式以進行探索。

可以放置在外掛程式目錄中的檔案有三種：

.sock 檔案是 Unix domain socket。
.spec 檔案是包含 URL 的文字檔，例如 unix:///other.sock 或 tcp://:8080。
.json 檔案是包含外掛程式完整 JSON 規格的文字檔。

使用 Unix domain socket 檔案的外掛程式必須與 Docker daemon 執行於同一台主機上。若指定遠端 URL，則使用 .spec 或 .json 檔案的外掛程式可以執行於不同主機上。

Unix domain socket 檔案必須放置於 /run/docker/plugins 下，而 spec 檔案則可放置於 /etc/docker/plugins 或 /usr/lib/docker/plugins 下。

檔案名稱（不含副檔名）即決定了外掛程式的名稱。

例如，flocker 外掛程式可能會在 /run/docker/plugins/flocker.sock 建立一個 Unix socket。

如果您想要隔離不同的定義，可以將每個外掛程式定義在獨立的子目錄中。例如，您可以在 /run/docker/plugins/flocker/flocker.sock 建立 flocker socket，並僅掛載 /run/docker/plugins/flocker 到 flocker 容器內。

Docker 總是會優先在 /run/docker/plugins 中搜尋 Unix socket。如果找不到 socket，它會檢查 /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 daemon，升級外掛程式，然後再啟動 Docker。

外掛程式啟用

當外掛程式首次被參照時——無論是使用者透過名稱參照（例如 docker run --volume-driver=foo），還是啟動已設定使用此外掛程式的容器——Docker 都會在外掛程式目錄中搜尋該命名的外掛程式，並透過交握 (handshake) 啟用它。請參閱下方的「交握 API」。

外掛程式不會在 Docker daemon 啟動時自動啟用。相反，它們是在需要時，以「延遲」或「隨需」(on-demand) 的方式啟用。

Systemd Socket 啟用

外掛程式也可以透過 systemd 進行 Socket 啟用。官方的外掛程式輔助工具原生支援 Socket 啟用。為了讓外掛程式能透過 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 daemon 連接到它們正在監聽的 socket 時真正啟動（例如當 daemon 第一次使用它們時，或者如果其中一個外掛程式意外崩潰）。

API 設計

Plugin API 是一種基於 HTTP 的 RPC 風格 JSON，很像 Webhook。

請求會從 Docker daemon 流向外掛程式。外掛程式需要實作一個 HTTP 伺服器，並將其綁定到「外掛程式探索」章節中提到的 Unix socket。

所有請求皆為 HTTP POST 請求。

API 透過 Accept 標頭進行版本控制，目前固定設定為 application/vnd.docker.plugins.v1+json。

交握 (Handshake) API

外掛程式透過以下「交握」(handshake) API 呼叫來啟用。

/Plugin.Activate

請求：空內文 (empty body)

回應 (Response)

{
    "Implements": ["VolumeDriver"]
}

回應為此外掛程式所實作的 Docker 子系統清單。啟用後，外掛程式將會接收來自該子系統的事件。

可能的值包括：

外掛程式重試機制

對外掛程式執行方法呼叫時，會以指數退避 (exponential backoff) 方式重試，最長可達 30 秒。這有助於將外掛程式封裝為容器的開發場景，因為它給了外掛程式容器啟動的時間，避免讓依賴它們的使用者容器過早失敗。

外掛程式輔助工具

為了簡化外掛程式開發，我們為 Docker 目前支援的每種外掛程式提供了 sdk，請參見 docker/go-plugins-helpers。