Docker Engine API
Docker 的架構
- 下圖是 Docker 官方的架構圖
- 由圖可知，Docker Client 與 Docker Host 是可以分開的
- 而我們一般運行 Docker，Client & Host 是同一台伺服器
- Docker Engine 提供了 Web API，讓你可以使用慣用的程式語言來控制 Docker Engine，甚至 Docker Container Apps 的數量(Scale Up/Down)
- 另外，Docker Engine 也提供了 SDK for Go & Python，熟悉這兩種語言的人，可以直接使用 SDK
- Docker Engine API 是 RESTful API，你可以很輕鬆地使用 wget, curl, powershell, 或是你慣用的程式語言來存取它。
- 要使用 Docker Engine API 之前，必須先知道你的 Docker Engine 版本所使用的 API 版本
查詢 Docker API 版本可以使用以下命令
docker version
啟用 Docker Engine API
Docker Engine API 預設是沒有啟動的，必須自行設定，設定步驟如下
- 開啟遠端 Docker Host 上的 Docker Service 設定檔
# 以 systemctl 讀取服務設定
# 第一行是設定檔路徑檔名
# 將第一行的註解符號去除掉，得到完整路徑檔名
# 存入環境變數
DOCKER_SERVICE_CONF_FILE=$(systemctl cat docker.service | head -n 1 | sed 's/^#\s//g')
vi ${DOCKER_SERVICE_CONF_FILE}
# vi /usr/lib/systemd/system/docker.service
-
修改其中 ExecStart 的命令，增加 -H tcp://0.0.0.0:2375 並存檔。
-
然後讓 systemd 重新載入 Daemon 相關設定檔，然後重新啟動 Docker
# 讓 systemd 重新載入 Daemon 設定檔
sudo systemctl daemon-reload
# 重新啟動 Docker Daemon
sudo systemctl restart docker
# 檢查 Docker Service 狀態
sudo systemctl status docker
如果有正常啟動 docker daemon 會看到如下圖
- 檢查 Docker 是否有監聽 2375 Port
sudo lsof -i -P -n | grep dockerd
sudo ss -tulpn | grep dockerd
以上就完成了啟用 Docker Engine API
Docker Engine API v1.43 簡單列舉容器相關操作
查詢 Container 資訊
Method: GET
http://{docker_host_ip}:2375/containers/json
| 參數 | 說明 |
|---|---|
| all | boolean，預設值為 false/0，表示只回傳正在運行的容器資訊；all=true/1，表示回傳所有容器資訊；注意這裡數值的布林值，與Python相同，只有0代表 false，其他數值，不管正負，都代表true |
| limit | integer，回傳最近幾個Container的資訊，包含沒有在運行的容器 |
| size | boolean，預設值為 false，回傳資訊增加容器大小 |
| filters | string，設定篩選容器的條件 |
可用的 filters
| 參數 | 說明 |
|---|---|
| ancestor | 指定 “ancestor”: [“image_name”:“image_tag”] |
| before | 指定 container_id 或 container_name之前的容器 |
| expose | 指定 expose port |
| exited | 指定 container exit code |
| health | 指定狀態：starting, healthy, unhealthy, none |
| id | 指定 Container ID |
| isolation | 指定隔離狀態：default, process, hyperv；Windows Daemon Only |
| label | 指定 {“label”:[“key”]} 或是 {“label”:[“key=value”]} |
| name | 指定Container Name |
| network | 指定 network_id 或 network_name |
| publish | 指定 port/proto 或 startport-endport/proto |
| since | 指定 container_id 或 container_name之後的容器 |
| status | 指定特定狀態的容器：created, restarting, running, removing, paused, exited, dead |
| volume | 指定volume_name 或 volume_id |
範例：
curl http://192.168.13.161:2375/containers/json?all=1
curl http://192.168.13.161:2375/v1.43/containers/json?filters={"ancestor": ["nginx:latest"]}
curl http://192.168.13.161:2375/containers/json?filters={"label":["CallFrom=Powershell"]}
查詢指定的 Container 資訊
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/json
查看 Container 內部運行的程式
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/top
查看 Container 運行的 Log
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/logs
查看 Container 內部被異動的檔案/目錄
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/changes
匯出 Container 並下載
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/export
持續回傳容器運行資源狀態(JSON)
Method: GET
http://{docker_host_ip}:2375/containers/[container_id | container_name]/stats
建立容器(注意：容器只有建立，並沒有運行)
Method: POST
http://{docker_host_ip}:2375/container/create
| 網址參數 | 說明 |
|---|---|
| name | string，必須符合正規式 ^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$ |
Header請指定 “Content-Type: application/json”
Body JSON 簡單列舉參數如下
| 參數名稱 | 說明 |
|---|---|
| Env | Array of Strings，指定環境變數及值 |
| Cmd | Array of Strings，指定容器啟動時，要執行的命令 |
| Image | string，指定容器要使用的 Image Name 以及 Tag |
| Volumes | 指定掛載的磁碟 |
| WorkingDir | 指定命令要在哪個目錄下運行 |
| Labels | 指定 Key/Value 的 Metadata |
| HostConfig | 設定網路相關資訊，例如：Port Mapping |
範例：
使用 bash shell curl 建立 Container
curl -X POST -H "Content-Type: application/json" \
-d '{"Image": "nginx:latest", "ExposedPorts": { "80/tcp": {} }, "HostConfig": { "PortBindings": { "80/tcp": [{ "HostIp": "", "HostPort": "9001" }] } } }' \
http://192.168.213.214:2375/containers/create
使用 Powershell 跑迴圈，建立三個 Container：web01, web02, web03，分別使用 Port 9001, 9002, 9003，並啟動這三個Container
$head = @{ 'Content-Type' = 'application/json' }
$Port = 9000
For($i=1; $i -le 3; $i++){
$Port++
$json = "{""Image"": ""nginx:latest"", "
$json += """ExposedPorts"": { ""80/tcp"": {} }, "
$json += """HostConfig"": { ""PortBindings"": { ""80/tcp"": [{ ""HostIp"": ""0.0.0.0"", ""HostPort"": ""$Port"" }] } }, "
$json += """Labels"" : {""CallFrom"":""Powershell""} }"
# Create Container
Invoke-RestMethod -Method POST -Uri ("http://192.168.13.161:2375/containers/create?name=web{0:d2}" -f $i) -Headers $head -Body $json
# Start Container
Invoke-RestMethod -Method POST -Uri ("http://192.168.13.161:2375/containers/web{0:d2}/start" -f $i) -Headers $head
}
啟動執行容器(Start)
Method: POST
http://{docker_host_ip}:2375/containers/[container_id | container_name]/start
停止運行容器(Stop)
Method: POST
http://{docker_host_ip}:2375/containers/[container_id | container_name]/stop
重新啟動執行容器(Restart)
Method: POST
http://{docker_host_ip}:2375/containers/[container_id | container_name]/restart
傳送 POSIX signal 給容器(Kill)
Method: POST
http://{docker_host_ip}:2375/containers/[container_id | container_name]/kill?signal=[SIGNAL_STRING | SIGNAL_CODE]
變更容器名稱(Rename)
Method: POST
http://{docker_host_ip}:2375/containers/[container_id | container_name]/rename?name=[new_container_name]
刪除容器名稱(Remove)
Method: DELETE
http://{docker_host_ip}:2375/containers/[container_id | container_name]
以上，當你使用錯誤的 Method 時，會顯示 page not found 錯誤訊息
參考資料
Configure remote access for Docker daemon
Docker Engine API (1.43)
Docker Engine API version history
Develop with Docker Engine SDKs
發表文章
