The Helm Plugins Guide

Helm 2.1.0 introduced the concept of a client-side Helm plugin. A plugin is atool that can be accessed through the helm CLI, but which is not part of thebuilt-in Helm codebase.

Existing plugins can be found on related section or by searching Github.

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 $(helm 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, withplugins being the plumbing. This is a shorthand way of suggesting thatHelm provides the user experience and top level processing logic, while theplugins do the "detail work" of performing a desired action.

Installing a Plugin

Plugins are installed using the $ helm plugin install <path|url> command. You can pass in a path to a plugin on your local file system or a url of a remote VCS repo. The helm plugin install command clones or copies the plugin at the path/url given into $ (helm home)/plugins

  1. $ helm plugin install https://github.com/technosophos/helm-template

If you have a plugin tar distribution, simply untar the plugin into the$(helm home)/plugins directory.

You can also install tarball plugins directly from url by issuing helm plugin install http://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.

  1. $(helm home)/plugins/
  2.   |- keybase/
  3.       |
  4.       |- plugin.yaml
  5.       |- 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 plugin YAML for a plugin that adds support for Keybase operations:

  1. name: "keybase"
  2. version: "0.1.0"
  3. usage: "Integrate Keybase.io tools with Helm"
  4. description: |-
  5.   This plugin provides Keybase services to Helm.
  6. ignoreFlags: false
  7. useTunnel: false
  8. command: "$HELM_PLUGIN_DIR/keybase.sh"

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 are both 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 —foois silently discarded.

The useTunnel switch indicates that the plugin needs a tunnel to Tiller. Thisshould be set to true anytime a plugin talks to Tiller. It will cause Helmto open a tunnel, and then set $TILLER_HOST to the right local address for thattunnel. But don't worry: if Helm detects that a tunnel is not necessary becauseTiller is running locally, it will not create the tunnel.

Finally, and most importantly, command is the command that this plugin willexecute when it is called. Environment variables are interpolated before the pluginis executed. The pattern above illustrates the preferred way to indicate wherethe plugin program lives.

There are some strategies for working with plugin commands:

  • If a plugin includes an executable, the executable for a command: should bepackaged in the plugin directory.
  • The command: line will have any environment variables expanded beforeexecution. $HELM_PLUGIN_DIR will point to the plugin directory.
  • The command itself is not executed in a shell. So you can't oneline a shell script.
  • 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 helm help myplugin,but will not handle helm myplugin —help.

Downloader Plugins

By default, Helm is able to fetch 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 (top level):

  1. downloaders:
  2. - command: "bin/mydownloader"
  3.   protocols:
  4.   - "myprotocol"
  5.   - "myprotocols"

If such plugin is installed, Helm can interact with the repository using the specifiedprotocol scheme by invoking the command. The special repository shall be addedsimilarly to the regular ones: helm repo add favorite myprotocol://example.com/The rules for the special repos are the same to the regular ones: Helm must be ableto download the index.yaml file in order to discover and cache the list ofavailable Charts.

The defined command will be invoked with the following scheme:command certFile keyFile caFile full-URL. The SSL credentials are coming from therepo definition, stored in $HELM_HOME/repository/repositories.yaml. Downloaderplugin is expected to dump the raw content to stdout and report errors on stderr.

The downloader command also supports sub-commands or arguments, allowing you to specifyfor example bin/mydownloader subcommand -d in the plugin.yaml. This is usefulif you want to use the same executable for the main plugin command and the downloadercommand, 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 theouter environment.

The following variables are guaranteed to be set:

  • HELM_PLUGIN: The path to the plugins directory
  • HELM_PLUGIN_NAME: The name of the plugin, as invoked by helm. Sohelm myplug 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_HOME: The path to the Helm home.
  • HELMPATH*: Paths to important Helm files and directories are stored inenvironment variables prefixed by HELM_PATH.
  • TILLERHOST: The domain:port to Tiller. If a tunnel is created, thiswill point to the local endpoint for the tunnel. Otherwise, it will pointto $HELM_HOST, —host, or the default host (according to Helm's rules ofprecedence).While HELM_HOST _may be set, there is no guarantee that it will point to thecorrect Tiller instance. This is done to allow plugin developer to accessHELM_HOST in its raw state when the plugin itself needs to manually configurea connection.

A Note on useTunnel

If a plugin specifies useTunnel: true, Helm will do the following (in order):

  • Parse global flags and the environment
  • Create the tunnel
  • Set TILLER_HOST
  • Execute the plugin
  • Close the tunnelThe tunnel is removed as soon as the command returns. So, for example, acommand cannot background a process and assume that process will be ableto use the tunnel.

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
  • —home: This is converted to $HELM_HOME
  • —host: This is converted to $HELM_HOST
  • —kube-context: This is simply dropped. If your plugin uses useTunnel, thisis used to set up the tunnel for you.Plugins should display help text and then exit for -h and —help. In allother cases, plugins may use flags as appropriate.