Creating a Helm Plugin in 3 Steps

Mar 21 2017

Helm is the package manager for Kubernetes. We recently added a plugin architecture to Helm that makes it easy for you to write new features in any programming language you choose.

In this post, we'll create a simple Helm plugin in three steps:

  • make a directory
  • create a plugin.yaml file
  • write a simple plugin in shell script

Step 1: Create a Directory

The first step in creating a plugin is to create a new directory to hold your plugin:

$ cd $(helm home)/plugins
$ mkdir hello
$ cd hello

Above, we first change into the plugins directory, and then we create a new directory named hello. Then we cd into that directory.

Step 2: Add a plugin.yaml File

The second step is to create a plugin.yaml file inside of our hello/ directory. This file contains some basic information about the plugin, including its name and the command we want it to run.

Here's my basic version:

name: "hello"
version: "0.1.0"
usage: "Say hello"
description: |-
  This is a demonstration plugin that prints Hello and then exists.
command: "env"

Each field provides a bit of information to Helm:

  • name: The "official" name of your plugin. It should be lower-case letters, numbers, and may contain the - character as long as - isn't the first or last character.
  • version: The version number for your plugin. This should follow the `SemVer 2 naming convention.
  • usage: This provides the short help text that will be displayed with helm -h.
  • description: This is the longer help text.
  • command: This is the command that will get executed.

With just this one file, we now have a working plugin. You can test it by running helm hello. It will print all of your environment variables to the console.

See, when Helm starts up, it reads the plugin's plugin.yaml file and maps the name field to a command name. (If we'd set name: bunny, then we would execute the plugin by running `helm bunny).

When the plugin is invoked, it executes whatever command is in the plugin.yaml's command: field. In our case, env is a built-in shell command that prints all environment variables.

Usually we want to do something a little more sophisticated than just running a shell command.

Step 3: Add A Custom Command

Along with plugin.yaml, we're going to create a second file in the hello/ directory. We'll name it helm-hello.sh (though the name doesn't really matter).

Our helm-hello.sh file will have a simple shell script:

#!/bin/bash

echo "Hello from a Helm plugin"

echo "PARAMS"
echo $*

echo "ENVIRONMENT"
echo $TILLER_HOST
echo $HELM_HOME

$HELM_BIN --host $TILLER_HOST ls --all

When run, this script does a few things:

  • It prints Hello from a Helm plugin
  • It prints out any parameters that were passed from the command line.
  • It prints a couple of built-in Helm environment variables.
  • It runs helm ls

This simple plugin is designed to show off a few features of the Helm plugin system:

  1. It can accept arguments that you define
  2. It has access to some useful environment variables, including:
    • $HELM_HOME: the location of Helm's configuration
    • $TILLER_HOST: the host and port that Tiller is listening on
    • $HELM_BIN: the path to the helm command on your system
    • $HELM_PLUGIN_DIR: the full path to this plugin (not shown above, but we'll see it in a moment).
  3. It can execute helm

In order to use the above, though, we need to make one small change to our plugin.yaml to tell it to call helm-hello.sh instead of env:

name: "hello"
version: "0.1.0"
usage: "Say hello"
description: |-
  This is a demonstration plugin that prints Hello and then exists.
command: "$HELM_PLUGIN_DIR/helm-hello.sh"

Now we've changed the command: to be $HELM_PLGUIN_DIR/helm-hello.sh. Helm will expand the $HELM_PLUGIN_DIR variable to unambiguously point to this plugin directory.

And that is all there is to writing a Helm plugin.

Conclusion

Helm plugins are supposed to be really easy to write. While we wrote ours in the Bash shell, you could just as easily write one in any language from Python to C to Elixir.

The plugin I talked about here is available on GitHub, along with a few more sophisticated examples.

And coming soon, Helm 2.3.0 will include a plugin manager that will make writing plugins even easier.