Helm插件指南

    已有插件可以搜索 GitHub。

    该指南描述如何使用和创建插件。

    Helm插件是与Helm无缝集成的附加工具。插件提供一种扩展Helm核心特性集的方法，但不需要每个新的特性都用Go编写并加入核心工具中。

    Helm插件有以下特性：

    • 可以在不影响Helm核心工具的情况下添加和移除。
    • 可以用任意编程语言编写。
    • 与Helm集成，并展示在helm help和其他地方。

    Helm插件存在与$HELM_PLUGINS。你可以找到该变量的当前值，包括不设置环境变量的默认值，使用helm env命令。

    Helm插件模型部分基于Git的插件模型。为此，你有时可能听到helm已插件为基础被用作_porcelain_ 层。这是一种Helm提供用户体验和顶级处理逻辑的简写方式。 而插件执行所需操作的“细节工作”。

    安装一个插件

    插件使用 $ helm plugin install <path|url> 命令安装插件。你可以在本地文件系统上传一个路径或远程仓库url给插件。The helm plugin install 命令会克隆或拷贝给定路径的插件到 $HELM_PLUGINS。

    如果是插件tar包，仅需解压插件到$HELM_PLUGINS目录。也可以用tar包的url直接安装： helm plugin install https://domain/path/to/plugin.tar.gz。

    在很多方面，插件类似于chart。每个插件有个顶级目录和一个plugin.yaml文件。

    1. $HELM_PLUGINS/
    2.   |- keybase/
    3.       |
    4.       |- plugin.yaml
    5.       |- keybase.sh

    上述示例中，keybase插件包含在keybase目录中。有两个文件：plugin.yaml（必需）和一个可执行脚本，keybase.sh（可选）。

    插件的核心是一个简单的YAML文件plugin.yaml。下面是一个插件YAML，用于添加对Keybase操作的支持：

    1. name: "last"
    2. version: "0.1.0"
    3. usage: "get the last release name"
    4. description: "get the last release name"
    5. ignoreFlags: false
    6. command: "$HELM_BIN --host $TILLER_HOST list --short --max 1 --date -r"
    7. platformCommand:
    8.   - os: linux
    9.     arch: i386
    10.     command: "$HELM_BIN list --short --max 1 --date -r"
    11.   - os: linux
    12.     arch: amd64
    13.     command: "$HELM_BIN list --short --max 1 --date -r"
    14.   - os: windows
    15.     arch: amd64
    16.     command: "$HELM_BIN list --short --max 1 --date -r"

    name是插件名称。当Helm执行此插件时使用此名称。（比如，helm NAME会调用此插件）。

    上述示例中，name应该匹配目录名称，意味着keybase目录中应该包含 name: keybase 插件。

    name的限制：

    • name 的字符必须限制为ASCII a-z， A-Z， 0-9， _ 和 -。

    ignoreFlags 开关告诉 Helm 不要 给插件传递的参数。因此如果一个插件使用 helm myplugin --foo调用且 ignoreFlags: true，那么--foo会被悄悄忽略。

    最后，尤其重要的是 platformCommand 或 command 是插件调用时执行的命令。platformCommand 部分定义了命令在 系统/架构的特定变体。以下规则用于决定使用哪个命令：

    • 如果platformCommand存在，会优先被搜索。
    • 如果os 和 arch 匹配了当前平台，搜索会停止并使用命令。
    • 如果os匹配且没有匹配 arch ，命令会被使用。
    • 如果没有匹配platformCommand，会使用默认的command。
    • 如果没有匹配 platformCommand 且不存在 ，Helm会报错退出。

    环境变量会在插件执行前被插入。上述模式说明了表示插件所在位置的首选方法。

    有一些使用插件命令的策略：

    • 如果插件中包含可执行文件，可执行文件针对于 platformCommand:或command:命令，应该打包到插件目录中。
    • platformCommand: 或者 command: 行会在执行之前展开任何环境变量。$HELM_PLUGIN_DIR会指向插件目录。
    • 命令本身不是在shell中执行的。 所以不能一行一个shell脚本。
    • Helm在环境变量中插入很多配置。查看环境变量获取可用信息。
    • Helm对插件语言不做任何假设。你想写什么写什么。
    • -h 和 --help命令负责实现特定的帮助文本。Helm会在helm help 和 helm help myplugin中使用usage 和 description，但不处理helm myplugin --help。

    下载插件

    默认情况下，Helm能够使用HTTP/S拉取chart。从Helm 2.4.0开始，插件有一种能力从任意来源下载chart。

    插件应该在plugin.yaml（顶层的）文件中声明这个特殊能力：

    如果这个插件已经安装，Helm可以通过调用command可以使用指定的协议方案与存储仓库进行交互。 特殊仓库的添加与常规仓库类似：helm repo add favorite myprotocol://example.com/。 特殊仓库的的规则也和常规仓库相同：为了发现和缓存chart的可用列表，Helm必须下载index.yaml文件。

    已定义的命令可以通过以下结构调用： command certFile keyFile caFile full-URL。SSL证书有仓库定义，存储在 $HELM_REPOSITORY_CONFIG(即：$HELM_CONFIG_HOME/repositories.yaml)。 下载器插件将原始内容使用stdout输出并使用stderr报告错误。

    下载器命令也支持子命令和参数，允许在plugin.yaml指定，比如bin/mydownloader subcommand -d。 如果你想在相同的可执行文件中执行主要的插件命令和下载器命令，这就变得很有用，但每个命令都有不同的子命令。

    当Helm执行插件时，会传递外部环境变量给插件，且会加入一些额外的环境变量。

    像 KUBECONFIG 这样的变量，如果是在外部环境中设置的，则是为插件设置的。

    要保证设置以下变量：

    • HELM_PLUGINS: 插件目录路径。
    • HELM_PLUGIN_NAME: helm调用的插件名称。
    • HELM_PLUGIN_DIR: 包含插件的目录。
    • HELM_BIN: （当前用户的）helm命令的路径。
    • HELM_DEBUG: 表示helm是否设置了debug。
    • 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

    从Helm 3.2开始，作为Helm现有的自动补全机制的一部分，插件可以选择性提供对shell自动补全的支持。

    如果插件提供了自己的参数或者子命令，可以通过位于插件根目录的completion.yaml文件通知 Helm。 completion.yaml格式如下：

    1. name: <pluginName>
    2. flags:
    3. - <flag 1>
    4. - <flag 2>
    5. validArgs:
    6. - <arg value 2>
    8.   name: <commandName>
    9.   flags:
    10.   - <flag 1>
    11.   - <flag 2>
    12.   validArgs:
    13.   - <arg value 1>
    14.   - <arg value 2>
    15.   commands:
    16.      <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 plugin，没有子命令但是接受 与helm status命令相同的参数，completion.yaml文件如下：

    1. name: fullstatus
    2. flags:
    3. - o
    4. - output
    5. - revision

    一个使用 更复杂的例子，completion.yaml文件如下：

    也是从Helm 3.2开始，插件可以提供它们自己的动态shell补全。动态补全是补全事先没有定义的参数值或标签值。比如说，补全集群中现在可用的helm发布的名称。

    对于支持动态补全的插件，必须在根目录中提供一个命名为plugin.complete的可执行文件。当Helm的自动补全脚本需要为这个插件动态补全时，会执行 plugin.complete文件，传递需要补全的命令行。plugin.complete可执行文件需要有判断核实补全选项的逻辑并将其通过Helm补全脚本输出到标准输出。

    plugin.complete文件是完全可选的。如果没有提供，Helm不会为插件提供动态自动补全。并且，添加plugin.complete文件是向后兼容的， 而且不会影响到插件使用Helm旧版本的操作。

    plugin.complete脚本的输出应该是以行分隔的列表，例如：

    1. rel1
    2. rel2
    3. 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执行如下：

    1. #!/usr/bin/env sh
    3. # "$@" is the entire command-line that requires completion.
    4. # It is important to double-quote the "$@" variable to preserve a possibly empty last parameter.
    5. $HELM_PLUGIN_DIR/status.sh --complete "$@"
    1. 脚本会自动过滤掉不匹配输入的补全。因此，插件会返回所有相关的补全，而不删除与用户输入不匹配的补全。比如，如果命令行是 helm fullstatus ngin<TAB>，不仅仅是以ngin开头的，plugin.complete 脚本可以打印 所有 （default默认命名空间）的发布名称， 脚本只会保留以ngin开头的。
    2. 为了简化动态补全支持，尤其是如果你有个复杂的插件，你可以有你的plugin.complete脚本调用你的主插件脚本并请求补全选项。查看上面 动态补全的例子。
    3. 要调试动态补全和plugin.complete文件，可以运行以下命令查看补全效果：
      • helm __complete <pluginName> <arguments to complete>。比如：
      • helm __complete fullstatus -o json ""<ENTER>