Helm 外掛程式指南

Helm 外掛程式是一種可以透過 helm CLI 存取的工具，但它不是內建 Helm 程式碼庫的一部分。

您可以在 相關 章節中找到現有的外掛程式，或透過搜尋 GitHub 來尋找。

本指南說明如何使用和建立外掛程式。

概述

Helm 外掛程式是與 Helm 無縫整合的附加工具。它們提供了一種擴展 Helm 核心功能集的方法，但不需要用 Go 語言編寫每個新功能並將其添加到核心工具中。

Helm 外掛程式具有以下功能

• 它們可以添加到 Helm 安裝中或從 Helm 安裝中移除，而不會影響核心 Helm 工具。
• 它們可以用任何程式語言編寫。
• 它們與 Helm 整合，並將顯示在 helm help 和其他地方。

Helm 外掛程式位於 $HELM_PLUGINS 中。您可以使用 helm env 命令找到此變數的目前值，包括未在環境中設定時的預設值。

Helm 外掛程式模型部分仿照 Git 的外掛程式模型。因此，您有時可能會聽到 helm 被稱為 *porcelain* 層，而外掛程式是 *plumbing*。這是一種簡略的說法，表示 Helm 提供使用者體驗和頂層處理邏輯，而外掛程式則執行「細節工作」來執行所需的動作。

安裝外掛程式

外掛程式使用 $ helm plugin install <路徑|網址> 命令安裝。您可以傳入本地檔案系統上外掛程式的路徑或遠端 VCS 儲存庫的網址。helm plugin install 命令會將指定路徑/網址上的外掛程式複製或複製到 $HELM_PLUGINS 中

$ helm plugin install https://github.com/adamreese/helm-env

如果您有外掛程式 tar 發佈版本，只需將外掛程式解壓縮到 $HELM_PLUGINS 目錄中即可。您也可以透過發出 helm plugin install https://網域/路徑/至/plugin.tar.gz 直接從網址安裝 tarball 外掛程式

建構外掛程式

在許多方面，外掛程式類似於圖表。每個外掛程式都有一個頂層目錄，然後是一個 plugin.yaml 檔案。

$HELM_PLUGINS/
  |- last/
      |
      |- plugin.yaml
      |- last.sh

在上面的範例中，last 外掛程式包含在名為 last 的目錄中。它有兩個檔案：plugin.yaml（必填）和一個可執行檔指令碼 last.sh（選填）。

外掛程式的核心是一個名為 plugin.yaml 的簡單 YAML 檔案。以下是一個外掛程式 YAML，用於協助取得最新的發行版本名稱

name: "last"
version: "0.1.0"
usage: "get the last release name"
description: "get the last release name"
ignoreFlags: false
command: "$HELM_BIN --host $TILLER_HOST list --short --max 1 --date -r"
platformCommand:
  - os: linux
    arch: i386
    command: "$HELM_BIN list --short --max 1 --date -r"
  - os: linux
    arch: amd64
    command: "$HELM_BIN list --short --max 1 --date -r"
  - os: windows
    arch: amd64
    command: "$HELM_BIN list --short --max 1 --date -r"

name 是外掛程式的名稱。當 Helm 執行此外掛程式時，它將使用此名稱（例如，helm NAME 將調用此外掛程式）。

*`name` 應與目錄名稱相符。* 在上面的範例中，這表示 name: last 的外掛程式應包含在名為 `last` 的目錄中。

`name` 的限制

• `name` 不能與現有的 `helm` 頂層命令重複。
• `name` 必須限制為 ASCII 字元 a-z、A-Z、0-9、`_` 和 `-`。

`version` 是外掛程式的 SemVer 2 版本。`usage` 和 `description` 都用於產生命令的說明文字。

`ignoreFlags` 開關告訴 Helm *不要* 將標誌傳遞給外掛程式。因此，如果使用 `helm myplugin --foo` 調用外掛程式，並且 `ignoreFlags: true`，則 `--foo` 會被靜默丟棄。

最後，也是最重要的，`platformCommand` 或 `command` 是此外掛程式在被調用時將執行的命令。`platformCommand` 章節定義了命令的作業系統/架構特定變體。以下規則將適用於決定使用哪個命令

• 如果存在 `platformCommand`，將首先搜尋它。
• 如果 `os` 和 `arch` 都與目前平台相符，搜尋將停止，並使用該命令。
• 如果 `os` 相符，並且沒有更具體的 `arch` 相符，則將使用該命令。
• 如果找不到 `platformCommand` 相符項，則將使用預設的 `command`。
• 如果在 `platformCommand` 中找不到相符項，並且不存在 `command`，Helm 將會以錯誤退出。

在執行外掛程式之前，會插入環境變數。上面的模式說明了指示外掛程式所在位置的首選方式。

有一些使用外掛程式命令的策略

• 如果外掛程式包含可執行檔，則 `platformCommand:` 或 `command:` 的可執行檔應打包在外掛程式目錄中。
• `platformCommand:` 或 `command:` 行將在執行前展開任何環境變數。`$HELM_PLUGIN_DIR` 將指向外掛程式目錄。
• 命令本身不是在 shell 中執行的。所以你不能單行執行 shell 指令碼。
• Helm 將大量配置注入環境變數中。查看環境以了解可用的資訊。
• Helm 對外掛程式的語言沒有任何假設。您可以用您喜歡的任何語言編寫它。
• 命令負責為 `-h` 和 `--help` 實現特定的說明文字。Helm 將使用 `usage` 和 `description` 處理 `helm help` 和 `helm help myplugin`，但不會處理 `helm myplugin --help`。

下載器外掛程式

預設情況下，Helm 可以使用 HTTP/S 拉取圖表。從 Helm 2.4.0 開始，外掛程式可以具有從任意來源下載圖表的特殊功能。

外掛程式應在 `plugin.yaml` 檔案（頂層）中聲明此特殊功能

downloaders:
- command: "bin/mydownloader"
  protocols:
  - "myprotocol"
  - "myprotocols"

如果安裝了此類外掛程式，Helm 可以透過調用 `command` 使用指定的通訊協定方案與儲存庫互動。特殊儲存庫的添加方式與常規儲存庫類似：`helm repo add favorite myprotocol://example.com/` 特殊儲存庫的規則與常規儲存庫相同：Helm 必須能夠下載 `index.yaml` 檔案才能發現和快取可用圖表的列表。

定義的命令將使用以下方案調用：`command certFile keyFile caFile full-URL`。SSL 憑證來自儲存庫定義，儲存在 `$HELM_REPOSITORY_CONFIG` 中（即 `$HELM_CONFIG_HOME/repositories.yaml`）。下載器外掛程式應將原始內容傾印到標準輸出，並在標準錯誤上報告錯誤。

下載器命令還支援子命令或參數，例如允許您在 `plugin.yaml` 中指定 `bin/mydownloader subcommand -d`。如果您想將同一個可執行檔用於主外掛程式命令和下載器命令，但每個命令使用不同的子命令，這將非常有用。

環境變數

當 Helm 執行外掛程式時，它會將外部環境傳遞給外掛程式，並注入一些額外的環境變數。

如果在外層環境中設定了 `KUBECONFIG` 等變數，則會為外掛程式設定這些變數。

保證會設定以下變數

• `HELM_PLUGINS`：外掛程式目錄的路徑。
• `HELM_PLUGIN_NAME`：外掛程式的名稱，由 `helm` 調用。因此 `helm myplug` 的簡稱將是 `myplug`。
• `HELM_PLUGIN_DIR`：包含外掛程式的目錄。
• `HELM_BIN`：`helm` 命令的路徑（由使用者執行）。
• `HELM_DEBUG`：指示 helm 是否設定了除錯標誌。
• HELM_REGISTRY_CONFIG：登錄檔配置的位置（如果使用）。請注意，Helm 與登錄檔一起使用是一項實驗性功能。
• HELM_REPOSITORY_CACHE：存放庫快取檔案的路徑。
• HELM_REPOSITORY_CONFIG：存放庫配置檔案的路徑。
• HELM_NAMESPACE：提供給 helm 命令的命名空間（通常使用 -n 旗標）。
• HELM_KUBECONTEXT：提供給 helm 命令的 Kubernetes 配置上下文的名稱。

此外，如果明確指定了 Kubernetes 配置檔，它將被設置為 KUBECONFIG 變數。

關於旗標解析的說明

執行外掛程式時，Helm 會解析全域旗標以供自身使用。這些旗標都不會傳遞給外掛程式。

• --debug：如果指定此旗標，則 $HELM_DEBUG 將被設置為 1。
• --registry-config：這將轉換為 $HELM_REGISTRY_CONFIG。
• --repository-cache：這將轉換為 $HELM_REPOSITORY_CACHE。
• --repository-config：這將轉換為 $HELM_REPOSITORY_CONFIG。
• --namespace 和 -n：這將轉換為 $HELM_NAMESPACE。
• --kube-context：這將轉換為 $HELM_KUBECONTEXT。
• --kubeconfig：這將轉換為 $KUBECONFIG。

外掛程式*應該*顯示說明文字，然後針對 -h 和 --help 旗標退出。在所有其他情況下，外掛程式可以酌情使用旗標。

提供 Shell 自動完成

從 Helm 3.2 開始，外掛程式可以選擇支援 Shell 自動完成，作為 Helm 現有自動完成機制的一部分。

靜態自動完成

如果外掛程式提供自己的旗標和/或子命令，它可以通過在其根目錄中放置一個 completion.yaml 檔案來通知 Helm。 completion.yaml 檔案的格式為：

name: <pluginName>
flags:
- <flag 1>
- <flag 2>
validArgs:
- <arg value 1>
- <arg value 2>
commands:
  name: <commandName>
  flags:
  - <flag 1>
  - <flag 2>
  validArgs:
  - <arg value 1>
  - <arg value 2>
  commands:
     <and so on, recursively>

注意事項

1. 所有區段都是可選的，但如果適用，則應提供。
2. 旗標不應包含 - 或 -- 前綴。
3. 可以且應該同時指定簡短和完整的旗標。簡短旗標不需要與其對應的完整形式關聯，但應列出兩種形式。
4. 旗標不需要按任何方式排序，但需要在檔案的子命令層次結構中的正確位置列出。
5. Helm 現有的全域旗標已由 Helm 的自動完成機制處理，因此外掛程式不需要指定以下旗標：--debug、--namespace 或 -n、--kube-context 和 --kubeconfig，或任何其他全域旗標。
6. validArgs 列表提供了子命令後第一個參數的可能完成的靜態列表。並非總是可以提前提供這樣的列表（請參閱下面的動態完成部分），在這種情況下，可以省略 validArgs 部分。

completion.yaml 檔案是完全可選的。如果未提供，Helm 將根本不為外掛程式提供 Shell 自動完成（除非外掛程式支援動態完成）。此外，新增 completion.yaml 檔案是向後相容的，並且在使用較舊的 helm 版本時不會影響外掛程式的行為。

例如，對於fullstatus 外掛程式，它沒有子命令，但接受與 helm status 命令相同的旗標，completion.yaml 檔案為：

name: fullstatus
flags:
- o
- output
- revision

一個更複雜的例子，2to3 外掛程式，有一個 completion.yaml 檔案：

name: 2to3
commands:
- name: cleanup
  flags:
  - config-cleanup
  - dry-run
  - l
  - label
  - release-cleanup
  - s
  - release-storage
  - tiller-cleanup
  - t
  - tiller-ns
  - tiller-out-cluster
- name: convert
  flags:
  - delete-v2-releases
  - dry-run
  - l
  - label
  - s
  - release-storage
  - release-versions-max
  - t
  - tiller-ns
  - tiller-out-cluster
- name: move
  commands:
  - name: config
    flags:
    - dry-run

動態完成

同樣從 Helm 3.2 開始，外掛程式可以提供自己的動態 Shell 自動完成。動態 Shell 自動完成是無法預先定義的參數值或旗標值的完成。例如，完成叢集上當前可用的 helm 版本的名稱。

為了讓外掛程式支援動態自動完成，它必須在其根目錄中提供一個名為 plugin.complete 的可執行檔案。當 Helm 完成指令碼需要外掛程式的動態完成時，它將執行 plugin.complete 檔案，並將需要完成的命令列傳遞給它。 plugin.complete 可執行檔案將需要具有確定正確完成選項的邏輯，並將它們輸出到標準輸出以供 Helm 完成指令碼使用。

plugin.complete 檔案是完全可選的。如果未提供，Helm 將根本不為外掛程式提供動態自動完成。此外，新增 plugin.complete 檔案是向後相容的，並且在使用較舊的 helm 版本時不會影響外掛程式的行為。

plugin.complete 指令碼的輸出應該是換行符分隔的列表，例如：

rel1
rel2
rel3

當呼叫 plugin.complete 時，外掛程式環境的設置與呼叫外掛程式的主指令碼時相同。因此，變數 $HELM_NAMESPACE、$HELM_KUBECONTEXT 和所有其他外掛程式變數都將已被設置，並且它們對應的全域旗標將被移除。

plugin.complete 檔案可以是任何可執行的形式；它可以是 Shell 指令碼、Go 程式或 Helm 可以執行的任何其他類型的程式。 plugin.complete 檔案*必須*具有使用者的可執行許可權。 plugin.complete 檔案*必須*以成功代碼（值 0）退出。

在某些情況下，動態完成將需要從 Kubernetes 叢集中獲取資訊。例如，helm fullstatus 外掛程式需要一個版本名稱作為輸入。在 fullstatus 外掛程式中，為了讓其 plugin.complete 指令碼為當前版本名稱提供完成，它可以簡單地運行 helm list -q 並輸出結果。

如果希望使用相同的可執行檔案進行外掛程式執行和外掛程式完成，則可以讓 plugin.complete 指令碼使用一些特殊的參數或旗標呼叫主外掛程式可執行檔案；當主外掛程式可執行檔案檢測到特殊的參數或旗標時，它將知道要運行完成。在我們的例子中，plugin.complete 可以像這樣實現：

#!/usr/bin/env sh

# "$@" is the entire command-line that requires completion.
# It is important to double-quote the "$@" variable to preserve a possibly empty last parameter.
$HELM_PLUGIN_DIR/status.sh --complete "$@"

然後，fullstatus 外掛程式的實際指令碼 (status.sh) 必須尋找 --complete 旗標，如果找到，則列印正確的完成。

提示和技巧

1. Shell 將自動篩選掉與使用者輸入不符的完成選項。因此，外掛程式可以返回所有相關的完成，而無需移除與使用者輸入不符的完成。例如，如果命令列是 helm fullstatus ngin<TAB>，則 plugin.complete 指令碼可以列印*所有*版本名稱（default 命名空間的），而不僅僅是以 ngin 開頭的版本名稱；Shell 將僅保留以 ngin 開頭的版本名稱。
2. 為了簡化動態完成支援，尤其是在您有一個複雜的外掛程式時，您可以讓您的 plugin.complete 指令碼呼叫您的主外掛程式指令碼並請求完成選項。有關示例，請參閱上面的動態完成部分。
3. 要除錯動態完成和 plugin.complete 檔案，可以運行以下命令以查看完成結果：
   • helm __complete <pluginName> <arguments to complete>。例如：
   • helm __complete fullstatus --output js<ENTER>,
   • helm __complete fullstatus -o json ""<ENTER>