The Helm Plugins Guide

The Helm Plugins Guide

A Helm plugin is a tool that can be accessed through the helm CLI, but whichis not part of the built-in Helm codebase.

Existing plugins can be found on related section orby searchingGithub.

This guide explains how to use and create plugins.

An Overview

Helm plugins are add-on tools that integrate seamlessly with Helm. They providea way to extend the core feature set of Helm, but without requiring every newfeature to be written in Go and added to the core tool.

Helm plugins have the following features:

They can be added and removed from a Helm installation without impacting thecore Helm tool.
They can be written in any programming language.
They integrate with Helm, and will show up in helm help and other places.Helm plugins live in $XDG_DATA_HOME/plugins.

The Helm plugin model is partially modeled on Git’s plugin model. To that end,you may sometimes hear helm referred to as the porcelain layer, with pluginsbeing the plumbing. This is a shorthand way of suggesting that Helm providesthe user experience and top level processing logic, while the plugins do the“detail work” of performing a desired action.

Installing a Plugin

Plugins are installed using the $ helm plugin install <path|url> command. Youcan pass in a path to a plugin on your local file system or a url of a remoteVCS repo. The helm plugin install command clones or copies the plugin at thepath/url given into $XDG_DATA_HOME/plugins

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

If you have a plugin tar distribution, simply untar the plugin into the $(helmhome)/plugins directory. You can also install tarball plugins directly from urlby issuing helm plugin install https://domain/path/to/plugin.tar.gz

Building Plugins

In many ways, a plugin is similar to a chart. Each plugin has a top-leveldirectory, and then a plugin.yaml file.

$XDG_DATA_HOME/plugins/
  |- keybase/
      |
      |- plugin.yaml
      |- keybase.sh

In the example above, the keybase plugin is contained inside of a directorynamed keybase. It has two files: plugin.yaml (required) and an executablescript, keybase.sh (optional).

The core of a plugin is a simple YAML file named plugin.yaml. Here is a pluginYAML for a plugin that adds support for Keybase operations:

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"

The name is the name of the plugin. When Helm executes it plugin, this is thename it will use (e.g. helm NAME will invoke this plugin).

name should match the directory name. In our example above, that means theplugin with name: keybase should be contained in a directory named keybase.

Restrictions on name:

name cannot duplicate one of the existing helm top-level commands.
name must be restricted to the characters ASCII a-z, A-Z, 0-9, _ and -.version is the SemVer 2 version of the plugin. usage and description areboth used to generate the help text of a command.

The ignoreFlags switch tells Helm to not pass flags to the plugin. So if aplugin is called with helm myplugin —foo and ignoreFlags: true, then—foo is silently discarded.

Finally, and most importantly, platformCommand or command is the commandthat this plugin will execute when it is called. The platformCommand sectiondefines the OS/Architecture specific variations of a command. The followingrules will apply in deciding which command to use:

If platformCommand is present, it will be searched first.
If both os and arch match the current platform, search will stop and thecommand will be used.
If os matches and there is no more specific arch match, the command willbe used.
If no platformCommand match is found, the default command will be used.
If no matches are found in platformCommand and no command is present, Helmwill exit with an error.Environment variables are interpolated before the plugin is executed. Thepattern above illustrates the preferred way to indicate where the plugin programlives.

There are some strategies for working with plugin commands:

If a plugin includes an executable, the executable for a platformCommand: ora command: should be packaged in the plugin directory.
The platformCommand: or command: line will have any environment variablesexpanded before execution. $HELM_PLUGIN_DIR will point to the plugindirectory.
The command itself is not executed in a shell. So you can’t oneline a shellscript.
Helm injects lots of configuration into environment variables. Take a look atthe environment to see what information is available.
Helm makes no assumptions about the language of the plugin. You can write itin whatever you prefer.
Commands are responsible for implementing specific help text for -h and—help. Helm will use usage and description for helm help and helmhelp myplugin, but will not handle helm myplugin —help.

Downloader Plugins

By default, Helm is able to pull Charts using HTTP/S. As of Helm 2.4.0, pluginscan have a special capability to download Charts from arbitrary sources.

Plugins shall declare this special capability in the plugin.yaml file (toplevel):

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

If such plugin is installed, Helm can interact with the repository using thespecified protocol scheme by invoking the command. The special repositoryshall be added similarly to the regular ones: helm repo add favoritemyprotocol://example.com/ The rules for the special repos are the same to theregular ones: Helm must be able to download the index.yaml file in order todiscover and cache the list of available Charts.

The defined command will be invoked with the following scheme: command certFilekeyFile caFile full-URL. The SSL credentials are coming from the repodefinition, stored in $XDG_DATA_HOME/helm/repositories.yaml. Downloader pluginis expected to dump the raw content to stdout and report errors on stderr.

The downloader command also supports sub-commands or arguments, allowing you tospecify for example bin/mydownloader subcommand -d in the plugin.yaml. Thisis useful if you want to use the same executable for the main plugin command andthe downloader command, but with a different sub-command for each.

Environment Variables

When Helm executes a plugin, it passes the outer environment to the plugin, andalso injects some additional environment variables.

Variables like KUBECONFIG are set for the plugin if they are set in the outerenvironment.

The following variables are guaranteed to be set:

HELM_PLUGINS: The path to the plugins directory.
HELM_PLUGIN_NAME: The name of the plugin, as invoked by helm. So helmmyplug will have the short name myplug.
HELM_PLUGIN_DIR: The directory that contains the plugin.
HELM_BIN: The path to the helm command (as executed by the user).
HELM_DEBUG: Indicates if the debug flag was set by helm.
HELM_REGISTRY_CONFIG: The location for the registry configuration (ifusing). Note that the use of Helm with registries is an experimental feature.
HELM_REPOSITORY_CACHE: The path to the repository cache files.
HELM_REPOSITORY_CONFIG: The path to the repository configuration file.
HELM_NAMESPACE: The namespace given to the helm command (generally usingthe -n flag).
HELM_KUBECONTEXT: The name of the Kubernetes config context given to thehelm command.Additionally, if a Kubernetes configuration file was explicitly specified, itwill be set as the KUBECONFIG variable

A Note on Flag Parsing

When executing a plugin, Helm will parse global flags for its own use. Some ofthese flags are not passed on to the plugin.

—debug: If this is specified, $HELM_DEBUG is set to 1
—kube-context: This is converted to $HELMKUBECONTEXTPlugins _should display help text and then exit for -h and —help. In allother cases, plugins may use flags as appropriate.