Creating a Helm Plugin in 3 Steps
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
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
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
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).
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
This simple plugin is designed to show off a few features of the Helm plugin system:
- It can accept arguments that you define
- 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
helmcommand on your system
$HELM_PLUGIN_DIR: the full path to this plugin (not shown above, but we'll see it in a moment).
- It can execute
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
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.
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.