【笔记】Helm-3 主题-12 Helm插件指南
Helm插件指南
Helm插件是一个可以通过helm CLI访问的工具，但不是Helm的内置代码。
已有插件可以搜索GitHub。
https://github.com/search?q=topic%3Ahelm-plugin&type=Repositories
该指南描述如何使用和创建插件。
概述
Helm插件是与Helm无缝集成的附加工具。插件提供一种扩展Helm核心特性集的方法，但不需要每个新的特性都用Go编写并加入核心工具中。
Helm插件有以下特性：
1、可以在不影响Helm核心工具的情况下添加和移除。
2、可以用任意编程语言编写。
3、与Helm集成，并展示在helm help和其他地方。
Helm插件存在与$HELM_PLUGINS。您可以找到该变量的当前值，包括不设置环境变量的默认值，使用helm env命令。
Helm插件模型部分基于Git的插件模型。为此，您有时可能听到helm以插件为基础被用作_porcelain_层。这是一种Helm提供用户体验和顶级处理逻辑的简写方式。而插件执行所需操作的“细节工作”。
安装一个插件
插件使用$ helm plugin install
$ helm plugin install https://github.com/adamreese/helm-env
$ helm plugin install https://github.com/adamreese/helm-env
如果是插件tar包，仅需要解压插件到$HELM_PLUGINS目录。也可以用tar包的url直接安装：helm plugin install https://domain/path/to/plugin.tar.gz。
构建插件
在很多方面，插件类似于chart。每个插件有个顶级目录和一个plugin.yaml文件。
$ HELM_PLUGINS/
$HELM_PLUGINS/
|- last/
|
|- plugin.yaml
|- last.sh上述示例中，last插件包含在last目录中。有两个文件：plugin.yaml（必须）和一个可执行脚本，last.sh（可选）。
插件的核心是一个简单的YAML文件plugin.yaml。下面是一个插件YAML，用于获取最新的release名称：
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 --max1 --date -r"
- os: windows
arch: amd64
command: "$HELM_BIN list --short --max 1 --date -r"
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应该匹配目录名称，意味着last目录中应该包含name: last插件。
name的限制：
1、name无法复用现有的helm顶级命令。
2、name的字符必须限制为ASCII a-z，A-Z，0-9，_和-。
version时插件的语意化2的版本。usage和description用于生成命令的帮助文本。
ignoreFlags开关告诉Helm不要给插件传递的参数。因此如果一个插件使用helm myplugin --foo调用且ignoreFlags: true，那么--foo会被悄悄忽略。
最后，尤其重要的是platformCommand或command是插件调用时执行的命令。platformCommand部分定义了命令在系统/架构的特定变体。以下规则用于决定使用哪个命令：
1、如果platformCommand存在，会优先被搜索。
2、如果os和arch匹配了当前平台，搜索会停止并使用命令。
3、如果没有匹配platformCommand且不存在command，Helm会报错退出。
环境变量会在插件执行前被插入。上述模式说明了表示插件所在位置的首选方法。
有一些使用插件命令的策略：
1、如果插件中包含可执行文件，可执行文件针对于platformCommand: 或command: 命令，应该打包到插件目录中。
2、platformCommand: 或者command: 行会在执行之前展开任何环境变量。$HELM_PLUGIN_DIR会指向插件目录。
3、Helm在环境变量中插入很多配置。查看环境变量获取可用信息。
4、Helm对插件语言不做任何假设。您想写什么就写什么。
5、-h和--help命令负责实现特定的帮助文本。Helm会在helm help和helm help myplugin中使用usage和description，但不处理helm myplugin --help。
下载插件
默认情况下，Helm能够使用HTTP/S拉去chart。从Helm 2.4.0开始，插件有一种能力从任意来源下载chart。
插件应该在plugin.yaml（顶层的）文件中声明这个特殊能力：
downloaders:
- command: "bin/mydownloader"
protocols:
- "myprotocol"
- "myprotocols"
downloaders:
- command: "bin/mydownloader"
protocols:
- "myprotocol"
- "myprotocols"如果这个插件已经安装，Helm可以通过调用command可以使用指定的协议方案与存储仓库进行交互。特殊仓库的添加与常规仓库类似：helm repo add favorite myprotocol://example.com/。特殊仓库的规则也和常规仓库相同：为了发现和缓存chart的可用列表，Helm必须下载index.yaml文件。
以定义的命令可以通过以下结构调用：command certiFile keyFile caFile full-URL。SSL证书有仓库定义，存储在$HELM_REPOSITORY_CONFIG(即：$HELM_CONFIG_HOME/repositories.yaml）。下载器插件将原始内容使用stdout输出并使用stderr报告错误。
下载器命令也支持子命令和参数，允许在plugin.yaml指定，比如bin/mydownloader subcommand -d。如果您想在相同的可执行文件中执行主要的插件命令和下载器命令，这就变得很有用，但每个命令都有不同的子命令。
环境变量
当Helm执行插件时，会传递外部环境变量给插件，且会加入一些额外的环境变量。
像KUBECONFIG这样的变量，如果实在外部环境中设置的，则是为插件设置的。
要保证设置以下变量：
HELM_PLUGIN:插件目录路径。
HELM_PLUGIN_NAME：helm调用的插件名称。
HELM_PLUGIN_DIR：包含插件的目录。
HELM_BIN：（当前用户的）helm命令的路径。
HELM_DEBUG：表示helm是否设置了debug。
HELM_REGISTRY_CONFIG:注册配置的位置（如果启用）。
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_REGISTRY_CACHE
--repository-config:链接到了$HELM_REPOSITORY_CONFIG
--namespace和-n:链接到了$HELM_NAMESPACE
--kube-context:链接到了$HELM_KUBECONTEXT
--kubeconfig:链接到了$KUBECONFIG
插件应该使用-h和--help显示帮助文本然后退出。在所有其他情况下，插件根据需要使用参数。
提供shell自动补全
从Helm 3.2开始，作为Helm现有的自动补全机制的一部分，插件可以选择性提供对shell自动补全的支持。
静态自动补全
如果插件提供了自己的参数或者子命令，可以通过位于插件跟目录的completion.yaml文件通知Helm。completion.yaml格式如下：
name:
flags:
-
-
validArgs:
-
-
commands:
name:
flags:
-
-
validArgs:
-
-
commands:
name:
flags:
-
-
validArgs:
-
-
commands:
name:
flags:
-
-
validArgs:
-
-
commands:
注意：
1、所有部分都是可选的，应该在适用时提供。
2、参数不该包含-或--前缀。
3、可以而且应该指定短的和长的参数。短参数不需要与其对应的长格式关联，但是都应被列出。
4、参数不需要以任何方式排序，但是需要列举出在文件子命令层次结构的正确位置。
5、Helm现有的全局参数已经有Helm的自动补全机制处理，因此插件不需要指定以下参数：--debug，--namespace或-n，--kube-context，以及--kubeconfig，或者其他全局参数。
6、validArgs列表提供了一个以下子命令的第一个参数可能补全的静态列表。并不总是能事先提供这样一份清单。（查看下面的 动态补全 部分），这种情况下validArgs部分可以省略。
Helm | Helm插件指南
completion.yaml文件是完全可选的。如果没有提供，Helm不会为插件提供shell自动补全功能（除非插件支持 动态补全 ）。并且，添加completion.yaml文件是向后兼容的，而且不会影响到插件使用helm旧版本的操作。
Helm | Helm插件指南
举个例子，针对fullstatus plugin，没有子命令但是接受与helm status命令相同的参数，completion.yaml文件如下：
name: fullsstatus
flags:
- o
- output
- revision
name: fullstatus
flags:
- o
- output
- revision一个使用2to3 plugin更复杂的例子，completion.yaml文件如下：
name: 2to3
commands:
- name: cleanup
flags:
- config-leanup
- 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
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-runDynamic completion
动态补全
也是从Helm3.2开始，插件可以提供它们自己的动态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
#!/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、脚本会自动过滤掉不匹配输入的补全。因此，插件会返回所有相关的补全，而不删除与用户输入不匹配的补全。比如，如果命令行是helm fullstatus ngin
2、为了简化动态补全支持，尤其是如果您有个复杂的插件，您可以有您的plugin.complete脚本调用您的主插件脚本并请求补全选项。查看上边 动态补全 的例子。
Helm | Helm插件指南
3、要调用动态补全和plugin.complete文件，可以运行以下命令查看补全效果：
helm_complete
helm_complete fullstatus --output js
helm_complete fullstatus -o json ""
helm __complete。比如：helm __complete fullstatus --output js，helm __complete fullstatus -o json ""
————————————
仅用于本人学习
来源：Helm | Docs