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。