Helm插件指南

Helm插件是一个可以通过helm CLI访问的工具,但不是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

$ 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/
  |- 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 --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的限制:

  • name 无法复用现有的 helm 顶级命令。
  • name 的字符必须限制为ASCII a-z, A-Z, 0-9, _-

version 是插件的语义化2的版本。 usagedescription 用于生成命令的帮助文本。

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

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

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

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

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

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

下载插件

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

插件应该在plugin.yaml(顶层的)文件中声明这个特殊能力:

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

如果这个插件已经安装,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

插件 应该 使用-h--help显示帮助文本然后退出。在所有其他情况下,插件根据需要使用参数。

提供shell自动补全

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

静态自动补全

如果插件提供了自己的参数或者子命令,可以通过位于插件根目录的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 plugin,没有子命令但是接受 与helm status命令相同的参数,completion.yaml文件如下:

name: fullstatus
flags:
- o
- output
- revision

一个使用 2to3 plugin更复杂的例子,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

Dynamic completion

也是从Helm 3.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

# "$@" 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<TAB>,不仅仅是以ngin开头的,plugin.complete 脚本可以打印 所有default默认命名空间)的发布名称, 脚本只会保留以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>