【笔记】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 <path|url> 命令安装插件。您可以在本地文件系统上传一个路径或远程仓库url给插件。The helm plugin install 命令会克隆或拷贝给定路径的插件到$ HELM_PLUGINS。

$ 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: linuxarch: i386command: "$HELM_BIN list --short --max 1 --date -r"- os: linuxarch: amd64command: "$HELM_BIN list --short --max 1 --date -r"- os: windowsarch: amd64command: "$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: <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>

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部分可以省略。

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: cleanupflags:- config-cleanup- dry-run- l- label- release-cleanup- s- release-storage- tiller-cleanup- t- tiller-ns- tiller-out-cluster
- name: convertflags:- delete-v2-releases- dry-run- l- label- s- release-storage- release-versions-max- t- tiller-ns- tiller-out-cluster
- name: movecommands:- name: configflags:- dry-run

Dynamic 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<TAB>，不仅仅是以ngin开头的，plugin.complete脚本可以打印所有（default默认命名空间）的发布名称，脚本只会保留以ngin开头的。

2、为了简化动态补全支持，尤其是如果您有个复杂的插件，您可以有您的plugin.complete脚本调用您的主插件脚本并请求补全选项。查看上边 动态补全 的例子。

Helm | Helm插件指南

3、要调用动态补全和plugin.complete文件，可以运行以下命令查看补全效果：

helm_complete <pluginName> <arguments to complete>。比如

helm_complete fullstatus --output js<ENTER>,

helm_complete fullstatus -o json ""<ENTER>

• helm __complete <pluginName> <arguments to complete>。比如：
• helm __complete fullstatus --output js<ENTER>，
• helm __complete fullstatus -o json ""<ENTER>

————————————

仅用于本人学习

来源：Helm | Docs