Capctl

Capctl 是 Captain-Kube 的 command line interface

Install

請依照 Installation#capctl 安裝, 安裝完成後可以使用 version 測試:

$ capctl version
# you should see the capctl version

如果你是透過 slctl 來安裝, 請將此篇列的所有指令 capctl 都改為 slctl cap 來執行

Chart controls

capctl 提供了許多 helm chart 壓縮檔的控制命令

install

上傳一或多個 Helm Chart 至 Captain-Kube

使用 --endpoint 指定上傳的 Captain Endpoint

$ capctl install CHART... -e CAPTAIN_ENDPOINT

若 Helm Tiller Server 不在 Captain-Kube 環境中, 可以傳入 --tiller* 開頭的 flag 設定 Tiller 相關資訊

$ capctl install CHART... -e CAPTAIN_ENDPOINT --tiller TILLER_IP
$ capctl install CHART... -e CAPTAIN_ENDPOINT --tiller TILLER_IP --tiller-skip-ssl=false

在上傳 Chart 之前, 支援以下 Pre-Procedures:

--pull : 拉取 Chart 中的 image

--retag-from 及 --retag-to : 將 Chart 中的 image tag 成指定 host 並推入該 docker registry

$ capctl install CHART... -e CAPTAIN_ENDPOINT -p
$ capctl install CHART... -e CAPTAIN_ENDPOINT -p -f hub.softleader.com.tw -t client-registry:5000

在上傳 Chart 之後, 支援以下 Post-Procedures:

--sync : 自動同步 image 到所有 kubernetes worker nodes, 如果當次上傳也有 re-tag 則會同步 re-tag 之後的 image

$ capctl install CHART... -e CAPTAIN_ENDPOINT -s
$ capctl install CHART... -e CAPTAIN_ENDPOINT -s -f hub.softleader.com.tw -t client-registry:5000

Pre-Procedures 跟 Post-Procedures 均可混合使用, 亦可結合 --reg-* 開頭的 flags 指定 docker registry 的認證資訊

$ capctl install CHART... -e CAPTAIN_ENDPOINT -ps --reg-pass SECRET

pull

拉取一或多個 Helm Chart 中的 image

$ capctl pull CHART...

如果 registry 需要登入, 可以傳入 --reg-* 開頭的 flags 指定 docker registry 的認證資訊

$ capctl pull CHART... --reg-user ME --reg-pass SECRET

如果需要在 pull 前修改 values.yaml 中任何參數, 可以傳入 --set key1=val1,key2=val2

$ capctl pull CHART... --set ingress.enabled=true

save

出一個或多個 Helm Chart 中的 image

傳入 --output 指定儲存的檔案路徑, docker 預設的儲存檔案格式為 tarball (.tar)

$ capctl save CHART... -o OUTPUT.tar

傳入 '--force' 可以強制複寫已存在的 output 檔案

$ capctl save CHART... -o OUTPUT.tar -f

如果需要在 save 前修改 values.yaml 中任何參數, 可以傳入 --set key1=val1,key2=val2

$ capctl save CHART... --set ingress.enabled=true

retag

將一或多個 Chart 中的 image tag 成指定 host 並推入該 docker registry

傳入 --retag-fro 及 --retag-to 指定 retag 的來源及目標, 只有符合 --retag-fro 的 image 才會被 retag

$ capctl retag CHART... -f hub.softleader.com.tw -t client-registry:5000

如果 registry 需要登入, 可以傳入 --reg-* 開頭的 flags 指定 docker registry 的認證資訊

$ capctl retag CHART... -f hub.softleader.com.tw -t client-registry:5000 --reg-pass SECRET

sync

同步一或多個 Helm Chart 中的 image 到所有 kubernetes worker nodes

$ capctl sync CHART... -e CAPTAIN_ENDPOINT

亦可結合 --retag-from 及 --retag-to, 同步 re-tag 之後的 image

$ capctl sync CHART... -e CAPTAIN_ENDPOINT -s -f hub.softleader.com.tw -t client-registry:5000

如果 registry 需要登入, 可以傳入 --reg-* 開頭的 flags 指定 docker registry 的認證資訊

$ capctl sync CHART... -e CAPTAIN_ENDPOINT --reg-pass SECRET

script

依照一或多個 Helm Chart 內容產生 docker scripts

傳入 flag 產生對應的 docker script

--pull    : docker pull IMAGE
--re-tag  : docker tag IMAGE NEW_IMAGE && docker push NEW_IMAGE
--save    : docker save IMAGE -o FILE
--load    : docker load -i FILE

flags 可以自由的混搭使用, 你也可以使用 '>' 再將產生的 script 輸出成檔案

$ capctl script CHART... -e CAPTAIN_ENDPOINT -prsl
$ capctl script CHART... -e CAPTAIN_ENDPOINT -sl > save-and-load.sh

結合 --diff 可以只產生差異 image 的 script

$ capctl script CHART ANOTHER_CHART -e CAPTAIN_ENDPOINT -prsld

如果需要在產生 script 前修改 values.yaml 中任何參數, 可以傳入 --set key1=val1,key2=val2

$ capctl script CHART... -e CAPTAIN_ENDPOINT --set ingress.enabled=true

若 --endpoint 不指定則可在當前執行環境下產生 script, 而不是交給 Captain 執行, 但請注意當前環境也必須要有產生 script 的必要 package

$ capctl script CHART...

可以結合 capctl ctx 指令: 清空 context, 執行 script 後, 再切回原 context

$ capctl ctx --off && capctl script CHART... && capctl ctx -

Docker controls

capctl 提供了一次控制所有 node 上 docker 的能力

prune

run docker system prune -f to current host and all worker nodes as well

$ capctl prune -e CAPTAIN_ENDPOINT

rmi

刪除一個或多個 docker image

使用 --endpoint 指定刪除的 Captain Endpoint

$ capctl rmi IMAGE:TAG... -e CAPTAIN_ENDPOINT

IMAGE 中可以使用 * 做模糊查詢, 如刪除包含 gateway 字眼的 image

$ capctl rmi hub.softleader.com.tw/*gateway*:TAG -e CAPTAIN_ENDPOINT

TAG 必須要指定, 可以是絕對條件或是 Semver2 的範圍條件 (https://devhints.io/semver)

$ capctl rmi IMAGE:2.1.3 -e CAPTAIN_ENDPOINT
$ capctl rmi IMAGE:^2.1.3 -e CAPTAIN_ENDPOINT
$ capctl rmi IMAGE:~2.1.3 -e CAPTAIN_ENDPOINT

傳入 --force 就算當前還有開啟 Container, 都強制刪除

$ capctl rmi IMAGE:TAG -e CAPTAIN_ENDPOINT --force

傳入 --dry-run 可以模擬真實的 rmi, 但不會真的刪除, 通常可以用來檢視 TAG 的 Semver2 範圍條件是否符合預期

$ capctl rmi IMAGE:<=2.0.0 -e CAPTAIN_ENDPOINT --dry-run

若 --endpoint 不指定則可在當前執行環境下執行 rmi, 而不是 Kubernetes cluster

$ capctl rmi IMAGE:TAG...

可以結合 capctl ctx 指令: 清空 context, 執行 rmi 後, 再切回原 context

$ capctl ctx --off && capctl rmi IMAGE:TAG... && capctl ctx -

rmc

刪除所有 node 上一個或多個 Chart 中的所有 image

使用 --endpoint 指定刪除的 Captain Endpoint

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT

傳入 --constraint 指定 TAG Semver2 的範圍條件 (https://devhints.io/semver)

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT -c "<"
$ capctl rmc CHART... -e CAPTAIN_ENDPOINT -c ^
$ capctl rmc CHART... -e CAPTAIN_ENDPOINT -c ~

傳入 --retag-from 及 --retag-to 可以刪除 retag 後的 image

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT -f hub.softleader.com.tw -t client-registry:5000

如果需要在 rmc 前修改 values.yaml 中任何參數, 可以傳入 '--set key1=val1,key2=val2'

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT --set ingress.enabled=true

傳入 --force 就算當前還有開啟 Container, 都強制刪除

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT --force

傳入 --dry-run 可以模擬真實的 rmi, 但不會真的刪除, 通常可以用來檢視 TAG 的 Semver2 範圍條件是否符合預期

$ capctl rmc CHART... -e CAPTAIN_ENDPOINT --dry-run

Context

Context 抽象化了 flags, 你可以視一個 context 為一組環境設定 將配置好的 context 啟用後, 會在執行任何 command 前被載入, command 使用的順序為:

1. 當前 command 執行時所傳入的 flag
2. 啟用中的 context-flags
3. 環境變數的設定

capctl ctx 指令可以快速的在不同 context 之間切換

$ capctl ctx         : 互動式的快速切換 context
$ capctl ctx <NAME>  : 切換 context 到 <NAME>
$ capctl ctx -       : 切換到前一個 context
$ capctl ctx --off   : 清空當前的 context

傳入 --ls 可以列出所有 context 及其 context-flags 配合 --width 可以指定顯示的字數 (預設100), --width 0 為不限長度, 即完整顯示

$ capctl ctx --ls
$ capctl ctx --ls --width 0

傳入 --add 可以新增 context, 結合 --force 可以強制複寫已存在的 context, 使用上需先接著一組 double-dash (--), 之後再給予1到數個 context-flags

$ capctl ctx -a <NAME> -- <CONTEXT_FLAGS...>
$ capctl ctx -a local -f -- -e localhost --endpoint-port 30051

傳入 --delete 或 --rename 可以刪除或重新命名 context:

$ capctl ctx -d <NAME>             : 刪除 context <NAME>
$ capctl ctx -d .                  : 刪除當前的 context
$ capctl ctx -r <NAME>=<NEW_NAME>  : 重新命名 <NAME> 成 <NEW_NAME>
$ capctl ctx -r .=<NEW_NAME>       : 重新命名當前的 context name 成 <NEW_NAME>