Helmプラグインガイド

Helmプラグインは、helm CLIを介してアクセスできるツールですが、組み込みのHelmコードベースの一部ではありません。

既存のプラグインは、関連セクションまたはGitHubを検索することで見つけることができます。

このガイドでは、プラグインの使い方と作成方法について説明します。

概要

Helmプラグインは、Helmとシームレスに統合するアドオンツールです。これにより、Goで記述してコアツールに追加する必要なく、Helmのコア機能セットを拡張できます。

Helmプラグインには、次の機能があります。

コアHelmツールに影響を与えることなく、Helmインストールに追加および削除できます。
任意のプログラミング言語で記述できます。
Helmと統合され、helm helpなどに表示されます。

Helmプラグインは$HELM_PLUGINSに格納されます。環境変数が設定されていない場合のデフォルト値を含む、この現在の値は、helm envコマンドを使用して確認できます。

Helmプラグインモデルは、部分的にGitのプラグインモデルをモデルにしています。そのため、helmはポーセレンレイヤー、プラグインは配管と呼ばれる場合があります。これは、Helmがユーザーエクスペリエンスとトップレベルの処理ロジックを提供し、プラグインが目的のアクションを実行する「詳細な作業」を行うことを示唆する省略表現です。

プラグインのインストール

プラグインは、$ helm plugin install <path|url>コマンドを使用してインストールされます。ローカルファイルシステム上のプラグインへのパス、またはリモートVCSリポジトリのURLを渡すことができます。helm plugin installコマンドは、指定されたパス/URLにあるプラグインを$HELM_PLUGINSにクローンまたはコピーします。

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

プラグインのtar配布ファイルがある場合は、$HELM_PLUGINSディレクトリにプラグインを展開するだけです。また、helm plugin install https://domain/path/to/plugin.tar.gzを実行することで、URLからtarballプラグインを直接インストールすることもできます。

プラグインのビルド

多くの点で、プラグインはチャートに似ています。各プラグインにはトップレベルのディレクトリとplugin.yamlファイルがあります。

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

上記の例では、lastプラグインはlastという名前のディレクトリに含まれています。これには、plugin.yaml（必須）と実行可能スクリプトlast.sh（オプション）の2つのファイルがあります。

プラグインの中核は、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セクションは、コマンドのOS/アーキテクチャ固有のバリエーションを定義します。使用されるコマンドを決定する際には、次のルールが適用されます。

platformCommandが存在する場合は、最初に検索されます。
osとarchの両方が現在のプラットフォームと一致する場合は、検索が停止し、コマンドが使用されます。
osが一致し、より具体的なarchの一致がない場合は、コマンドが使用されます。
platformCommandで一致が見つからず、commandが存在しない場合は、Helmはエラーで終了します。
platformCommandに一致が見つからず、commandが存在しない場合は、Helmはエラーで終了します。

環境変数は、プラグインが実行される前に補間されます。上記の例は、プラグインプログラムの場所を示す推奨方法を示しています。

プラグインコマンドを操作するためのいくつかの戦略があります。

プラグインに実行可能ファイルが含まれている場合、platformCommand:またはcommand:の実行可能ファイルはプラグインディレクトリにパッケージ化する必要があります。
platformCommand:またはcommand:行では、実行前に環境変数が展開されます。$HELM_PLUGIN_DIRはプラグインディレクトリを指します。
コマンド自体はシェルでは実行されません。そのため、シェルスクリプトを1行で記述することはできません。
Helmは多くの構成を環境変数に挿入します。利用可能な情報を確認するには、環境を確認してください。
Helmはプラグインの言語について何も想定しません。好きな言語で記述できます。
コマンドは、-hと--helpの具体的なヘルプテキストを実装する責任があります。Helmはhelm helpとhelm help mypluginにusageとdescriptionを使用しますが、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）に格納されているリポジトリ定義から取得されます。ダウンローダープラグインは、生のコンテンツをstdoutにダンプし、stderrにエラーを報告する必要があります。

ダウンローダーコマンドは、サブコマンドまたは引数もサポートしているため、たとえばbin/mydownloader subcommand -dをplugin.yamlで指定できます。これは、メインプラグインコマンドとダウンローダーコマンドに同じ実行可能ファイルを使用したいが、それぞれに異なるサブコマンドを使用する場合に役立ちます。

環境変数

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 config contextの名前。

さらに、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に対してヘルプテキストを表示してから終了する必要があります。その他の場合、プラグインは必要に応じてフラグを使用できます。

シェルオートコンプリートの提供

Helm 3.2以降、プラグインは、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>

注意事項

すべてのセクションはオプションですが、該当する場合は提供する必要があります。
フラグには、-または--プレフィックスを含めることはできません。
短縮形と長形式の両方のフラグを指定する必要があり、また指定することができます。短縮形は対応する長形式と関連付ける必要はありませんが、両方の形式をリストする必要があります。
フラグは特定の順序で並べる必要はありませんが、ファイルのサブコマンド階層内の正しい位置にリストする必要があります。
Helmの既存のグローバルフラグは、Helmのオートコンプリートメカニズムによって既に処理されているため、プラグインは--debug、--namespaceまたは-n、--kube-context、--kubeconfig、またはその他のグローバルフラグを指定する必要はありません。
validArgsリストは、サブコマンドの後に続く最初のパラメーターの可能な補完の静的なリストを提供します。事前にこのようなリストを提供することは常に可能とは限りません（下記の動的補完セクションを参照）。その場合、validArgsセクションは省略できます。

completion.yamlファイルは完全にオプションです。これが提供されない場合、Helmはプラグインに対してシェルオートコンプリートを提供しません（動的補完がプラグインでサポートされている場合を除く）。また、completion.yamlファイルを追加しても、古いバージョンのhelmを使用する場合、プラグインの動作に影響はありません。

例として、サブコマンドを持たないがhelm statusコマンドと同じフラグを受け入れるfullstatusプラグインの場合、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以降、プラグインは独自の動的なシェルオートコンプリートを提供できます。動的なシェルオートコンプリートとは、事前に定義できないパラメーター値またはフラグ値の補完です。たとえば、クラスタで現在使用可能な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ファイルは、実行可能な形式であればどのような形式でもかまいません。シェルスクリプト、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フラグを探し、見つかった場合は、適切な補完を出力する必要があります。

ヒントとコツ

シェルは、ユーザー入力と一致しない補完の選択肢を自動的にフィルタリングします。したがって、プラグインは、ユーザー入力と一致しないものを削除せずに、すべての関連する補完を返すことができます。たとえば、コマンドラインがhelm fullstatus ngin<TAB>の場合、plugin.completeスクリプトはnginで始まるものだけでなく、すべてのリリース名（default名前空間のもの）を出力できます。シェルは、nginで始まるものだけを保持します。
特に複雑なプラグインの場合、動的な補完サポートを簡素化するために、plugin.completeスクリプトでメインプラグインスクリプトを呼び出して、補完の選択肢を要求できます。例については、上記の動的補完セクションを参照してください。
動的な補完とplugin.completeファイルをデバッグするには、次のコマンドを実行して補完の結果を確認できます。
- helm __complete <pluginName> <補完する引数>。例：
- helm __complete fullstatus --output js<ENTER>,
- helm __complete fullstatus -o json ""<ENTER>