使用外掛程式擴充 kubectl

本指南示範如何安裝和撰寫 kubectl 的擴充功能。透過將核心 kubectl 命令視為與 Kubernetes 叢集互動的基本建構區塊，叢集管理員可以將外掛程式視為利用這些建構區塊來建立更複雜行為的方法。外掛程式使用新的子命令擴充 kubectl，允許新增和自訂功能，這些功能未包含在 kubectl 的主要發行版本中。

開始之前

您需要安裝可運作的 kubectl 二進位檔。

安裝 kubectl 外掛程式

外掛程式是獨立的可執行檔，其名稱以 kubectl- 開頭。若要安裝外掛程式，請將其可執行檔移動到 PATH 上的任何位置。

您也可以使用 Krew 探索和安裝開放原始碼中提供的 kubectl 外掛程式。Krew 是由 Kubernetes SIG CLI 社群維護的外掛程式管理器。

探索外掛程式

kubectl 提供命令 kubectl plugin list，可在您的 PATH 中搜尋有效的插件可執行檔。執行此命令會導致遍歷 PATH 中的所有檔案。任何可執行且以 kubectl- 開頭的檔案都會依其在 PATH 中的順序顯示在此命令的輸出中。對於任何以 kubectl- 開頭但不是可執行檔的檔案，都會包含警告。對於任何名稱相互重疊的有效外掛程式檔案，也會包含警告。

您可以使用 Krew 從社群策劃的 外掛程式索引 探索和安裝 kubectl 外掛程式。

建立外掛程式

kubectl 允許外掛程式透過在 PATH 中提供 kubectl-create-something 二進位檔，來新增形狀為 kubectl create something 的自訂建立命令。

限制

目前無法建立覆寫現有 kubectl 命令或擴充 create 以外命令的外掛程式。例如，建立外掛程式 kubectl-version 將導致該外掛程式永遠不會執行，因為現有的 kubectl version 命令將始終優先於它。由於此限制，也無法使用外掛程式將新的子命令新增至現有的 kubectl 命令。例如，透過將外掛程式命名為 kubectl-attach-vm 來新增子命令 kubectl attach vm 將導致該外掛程式被忽略。

kubectl plugin list 會針對任何嘗試執行此操作的有效外掛程式顯示警告。

撰寫 kubectl 外掛程式

您可以使用任何程式語言或指令碼撰寫外掛程式，讓您能夠撰寫命令列命令。

無需外掛程式安裝或預先載入。外掛程式可執行檔會接收來自 kubectl 二進位檔的繼承環境。外掛程式會根據其名稱判斷它想要實作的命令路徑。例如，名為 kubectl-foo 的外掛程式提供命令 kubectl foo。您必須將外掛程式可執行檔安裝在 PATH 中的某個位置。

外掛程式範例

#!/bin/bash

# optional argument handling
if [[ "$1" == "version" ]]
then
    echo "1.0.0"
    exit 0
fi

# optional argument handling
if [[ "$1" == "config" ]]
then
    echo "$KUBECONFIG"
    exit 0
fi

echo "I am a plugin named kubectl-foo"

使用外掛程式

若要使用外掛程式，請使外掛程式可執行

sudo chmod +x ./kubectl-foo

並將其放置在 PATH 中的任何位置

sudo mv ./kubectl-foo /usr/local/bin

您現在可以將您的外掛程式作為 kubectl 命令調用

kubectl foo

I am a plugin named kubectl-foo

所有引數和旗標都會原封不動地傳遞至可執行檔

kubectl foo version

1.0.0

所有環境變數也會原封不動地傳遞至可執行檔

export KUBECONFIG=~/.kube/config
kubectl foo config

/home/<user>/.kube/config

KUBECONFIG=/etc/kube/config kubectl foo config

/etc/kube/config

此外，傳遞給外掛程式的第一個引數將始終是調用它的位置的完整路徑（在上面的範例中，$0 將等於 /usr/local/bin/kubectl-foo）。

命名外掛程式

如上面的範例所示，外掛程式會根據其檔案名稱判斷它將實作的命令路徑。外掛程式目標的命令路徑中的每個子命令都以破折號 (-) 分隔。例如，每當使用者調用命令 kubectl foo bar baz 時想要被調用的外掛程式，其檔案名稱將為 kubectl-foo-bar-baz。

旗標和引數處理

kubectl 外掛程式必須解析並驗證傳遞給它們的所有引數。請參閱使用命令列執行時期套件以取得針對外掛程式作者設計的 Go 程式庫的詳細資訊。

以下是一些額外的情境，使用者在呼叫您的外掛程式時會提供額外的旗標和引數。這建立在上述情境中的 kubectl-foo-bar-baz 外掛程式之上。

如果您執行 kubectl foo bar baz arg1 --flag=value arg2，kubectl 的外掛機制會先嘗試尋找名稱最長的外掛程式，在此例中會是 kubectl-foo-bar-baz-arg1。在找不到該外掛程式後，kubectl 接著會將最後一個以破折號分隔的值視為引數（在此例中為 arg1），並嘗試尋找次長名稱的外掛程式，kubectl-foo-bar-baz。在找到具有此名稱的外掛程式後，kubectl 便會呼叫該外掛程式，並將外掛程式名稱後的所有引數和旗標作為引數傳遞給外掛程式程序。

範例

# create a plugin
echo -e '#!/bin/bash\n\necho "My first command-line argument was $1"' > kubectl-foo-bar-baz
sudo chmod +x ./kubectl-foo-bar-baz

# "install" your plugin by moving it to a directory in your $PATH
sudo mv ./kubectl-foo-bar-baz /usr/local/bin

# check that kubectl recognizes your plugin
kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-foo-bar-baz

# test that calling your plugin via a "kubectl" command works
# even when additional arguments and flags are passed to your
# plugin executable by the user.
kubectl foo bar baz arg1 --meaningless-flag=true

My first command-line argument was arg1

如您所見，您的外掛程式是根據使用者指定的 kubectl 指令找到的，並且一旦找到，所有額外的引數和旗標都會原封不動地傳遞給外掛程式執行檔。

帶有破折號和底線的名稱

雖然 kubectl 外掛機制在插件檔案名稱中使用破折號 (`-`) 來分隔外掛程式處理的子指令序列，但仍然可以透過在檔案名稱中使用底線 (`_`) 來建立在命令列呼叫中包含破折號的外掛程式指令。

範例

# create a plugin containing an underscore in its filename
echo -e '#!/bin/bash\n\necho "I am a plugin with a dash in my name"' > ./kubectl-foo_bar
sudo chmod +x ./kubectl-foo_bar

# move the plugin into your $PATH
sudo mv ./kubectl-foo_bar /usr/local/bin

# You can now invoke your plugin via kubectl:
kubectl foo-bar

I am a plugin with a dash in my name

請注意，在外掛程式檔案名稱中引入底線並不會阻止您擁有例如 kubectl foo_bar 之類的指令。上述範例中的指令可以使用破折號 (`-`) 或底線 (`_`) 來呼叫。

# You can invoke your custom command with a dash
kubectl foo-bar

I am a plugin with a dash in my name

# You can also invoke your custom command with an underscore
kubectl foo_bar

I am a plugin with a dash in my name

名稱衝突和遮蔽

在您的 PATH 中不同的位置，可能有多個具有相同檔案名稱的外掛程式。例如，給定一個具有以下值的 PATH：PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins，外掛程式 kubectl-foo 的副本可能存在於 `/usr/local/bin/plugins` 和 `/usr/local/bin/moreplugins` 中，使得 `kubectl plugin list` 指令的輸出為

PATH=/usr/local/bin/plugins:/usr/local/bin/moreplugins kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/plugins/kubectl-foo
/usr/local/bin/moreplugins/kubectl-foo
  - warning: /usr/local/bin/moreplugins/kubectl-foo is overshadowed by a similarly named plugin: /usr/local/bin/plugins/kubectl-foo

error: one plugin warning was found

在上述情境中，`/usr/local/bin/moreplugins/kubectl-foo` 下的警告告訴您，此外掛程式永遠不會被執行。相反地，PATH 中首先出現的可執行檔，`/usr/local/bin/plugins/kubectl-foo`，將始終由 kubectl 外掛機制首先找到並執行。

解決此問題的一種方法是確保您希望與 kubectl 一起使用的外掛程式位置始終在您的 PATH 中排在第一位。例如，如果您希望在每次呼叫 `kubectl` 指令 `kubectl foo` 時始終使用 `/usr/local/bin/moreplugins/kubectl-foo`，請將您的 `PATH` 值更改為 `/usr/local/bin/moreplugins:/usr/local/bin/plugins`。

呼叫最長的可執行檔名稱

還有另一種遮蔽可能會發生在外掛程式檔案名稱上。假設使用者的 `PATH` 中存在兩個外掛程式：`kubectl-foo-bar` 和 `kubectl-foo-bar-baz`，對於給定的使用者指令，`kubectl` 外掛機制將始終選擇最長的外掛程式名稱。以下是一些範例，進一步闡明這一點

# for a given kubectl command, the plugin with the longest possible filename will always be preferred
kubectl foo bar baz

Plugin kubectl-foo-bar-baz is executed

kubectl foo bar

Plugin kubectl-foo-bar is executed

kubectl foo bar baz buz

Plugin kubectl-foo-bar-baz is executed, with "buz" as its first argument

kubectl foo bar buz

Plugin kubectl-foo-bar is executed, with "buz" as its first argument

這種設計選擇確保了外掛程式子指令可以在多個檔案中實作（如果需要），並且這些子指令可以巢狀在「父」外掛程式指令下。

ls ./plugin_command_tree

kubectl-parent
kubectl-parent-subcommand
kubectl-parent-subcommand-subsubcommand

檢查外掛程式警告

您可以使用前面提到的 `kubectl plugin list` 指令來確保您的外掛程式對 `kubectl` 可見，並驗證沒有任何警告阻止它作為 `kubectl` 指令被呼叫。

kubectl plugin list

The following kubectl-compatible plugins are available:

test/fixtures/pkg/kubectl/plugins/kubectl-foo
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo is overshadowed by a similarly named plugin: test/fixtures/pkg/kubectl/plugins/kubectl-foo
plugins/kubectl-invalid
  - warning: plugins/kubectl-invalid identified as a kubectl plugin, but it is not executable

error: 2 plugin warnings were found

使用命令列執行時期套件

如果您正在為 kubectl 編寫外掛程式並且您正在使用 Go，則可以使用 cli-runtime 实用程式庫。

這些程式庫提供助手，用於解析或更新使用者的 kubeconfig 檔案、向 API 伺服器發出 REST 樣式的請求，或綁定與配置和列印相關聯的旗標。

請參閱 範例 CLI 外掛程式，以取得 CLI Runtime 儲存庫中提供的工具的範例用法。

發布 kubectl 外掛程式

如果您開發了一個外掛程式供其他人使用，您應該考慮如何封裝它、發布它以及向您的使用者交付更新。

Krew

Krew 提供了一種跨平台的方式來封裝和發布您的外掛程式。透過這種方式，您可以為所有目標平台（Linux、Windows、macOS 等）使用單一封裝格式，並向您的使用者交付更新。Krew 還維護一個外掛程式索引，以便其他人可以發現您的外掛程式並安裝它。

原生/平台特定套件管理

或者，您可以使用傳統的套件管理器，例如 Linux 上的 apt 或 yum、Windows 上的 Chocolatey 和 macOS 上的 Homebrew。任何套件管理器只要能將新的可執行檔放置在使用者的 PATH 中的某個位置即可。作為外掛程式作者，如果您選擇此選項，那麼您還必須承擔在每個版本中跨多個平台更新您的 kubectl 外掛程式發布套件的負擔。

原始碼

您可以發布原始碼；例如，作為 Git 儲存庫。如果您選擇此選項，想要使用此外掛程式的人必須取得程式碼、設定建置環境（如果需要編譯）並部署外掛程式。如果您也提供已編譯的套件，或使用 Krew，那將使安裝更容易。

接下來

• 查看範例 CLI 外掛程式儲存庫，以取得以 Go 語言編寫的外掛程式的詳細範例。如有任何疑問，請隨時與 SIG CLI 團隊聯繫。
• 閱讀關於 Krew 的資訊，它是 kubectl 外掛程式的套件管理器。