Forem: Roman Labunsky

How to build a Helm plugin in minutes

Roman Labunsky — Wed, 16 Jun 2021 13:39:58 +0000

Introduction

Helm is a great addition to the Kubernetes ecosystem; it simplifies complex Kubernetes manifests by separating them into charts and values.

Sharing charts has never been easier especially since all the customizable parameters are located separately (values.yaml). The downside of this is that there’s no single place to see the resulting manifest, as it’s usually compiled and installed in a single step - helm install.

Helm alleviates this with a plugin system that allows you to seamlessly integrate with the Helm flow and easily run custom code that’s not part of the Helm core code which, as we’ll see in the next section, can be written in any language, even Bash.

A simple example of how to create a Helm plugin

Let's build a simple plugin that prints out some useful information and environment variables that Helm provides.

A helm plugin consists of a single required file - plugin.yaml

That’s the entrypoint for Helm. By using this, Helm knows the settings for your plugin, the command it executes when the plugin is run and hooks for customizing the plugin lifecycle (more on that later).

This is the only required file for a complete plugin. You can set it up in 3 steps:

Create a plugin.yaml with the following content
Run the installation command from the directory of the file
```
helm plugin install .
```
Execute the plugin
```
helm myplugin
```

A complete example of a Helm plugin

The simple plugin example covers the most basic use cases, goals that can be achieved even with an alias. More complex cases require more points of integration with Helm and greater customizability of the plugin’s lifecycle. The following parts will give you all the necessary tools to execute any logic in the Helm flow.

Lifecycle customization - Install, update and delete hooks

Helm provides under-documented (the closest thing I found to documentation was here) capability for hooking into the plugin’s install, update or uninstall commands.

Each hook corresponds to a command and will execute the provided script when invoked.

Some plugins may require a more complex installation flow: Downloading a binary based on OS architecture, building or compiling code or simply installing system dependencies. The install script is the place to do it. A useful example can be found here.

Execution integration

There are two ways to specify what will be executed and when:

command

platformCommand

It's important to note that Helm has a hierarchy for choosing the correct command:

platformCommand(os+arch match)
platformCommand(os only match)
command

Helm plugins aren’t executed in a shell, so complex commands must be part of a script that will be executed every time the plugin is invoked.

A script can be used to run complex logic, handle parameter parsing, etc.

command: "$HELM_PLUGIN_DIR/scripts/run.sh"

A comprehensive example of a run script can be found here. A very useful thing that we can do is to render the chart and then execute logic on the resulting Kubernetes yaml file:

helm template "${HELM_OPTIONS[@]}" > ${TEMP_MANIFEST_NAME}

$HELM_PLUGIN_DIR/bin/myplugin ${TEMP_MANIFEST_NAME} "${MYPLUGIN_OPTIONS[@]}"

A very important flag in plugin.yaml is:

ignoreFlags: false

This flag specifies whether or not the command line params are passed to the plugin or not. If the plugin accepts parameters, this should be set to false.

Tips and caveats

Helm exposes many environment variables that can simplify a lot of the complex logic and provides much of the necessary information and context for the plugin’s execution.
The useTunnel flag in config.yaml is deprecated in Helm V3 and is no longer needed
To easily test the plugin during development, you can install the plugin from the dev directory by running helm plugin install PATH_TO_DIR
The plugin can then be uninstalled with helm plugin uninstall PLUGIN_NAME

Conclusion

Helm plugin writing is easy to learn but difficult to master. Lack of documentation makes writing complex plugins an arduous task.

This article aims to expose some of the lesser known abilities of the Helm plugin system and to provide tools and scaffolding that remove the limitations of the plugin system and allow execution of as complex a business logic as is necessary to extend Helm’s behavior.

A guide to GitHub Actions using Node.js for Git workflow automation

Roman Labunsky — Sun, 31 Mar 2019 18:09:26 +0000

What is Github Actions?

GitHub Actions, a feature announced in October 2018 during GitHub Universe, generated immense hype under the apt positioning as the “swiss army knife” of git workflow automation.

Github Actions allows developers to perform tasks automatically in a Github workflow, such as pushing commits to a repository, deploying a release to staging, running tests, removing feature flags, and so on, by way of a simple text file.

Chewy.com, for example, demoed an action that checks if a Jira ticket number is included in every pull request name among other things, to ensure the code being deployed to production is compliant with their policies and best practices.

“With GitHub Actions, you can automate your workflow from idea to production.”

– GitHub actions page

Write Github Actions in Node.js

I started tinkering with the feature as soon as I could get access to the private beta. I noticed that most Actions are written in shell script. GitHub itself promoted writing actions in shell script for simple actions. While I understand the motivation (so you can quickly and easily start writing Actions), I feel that shell scripts are limited in terms of writing full-fledged software.

Since I generally work in Node.js, I decided to ‘accept the challenge’ and write my first Action in Node. But, after struggling with the specifics of running Node.js actions and understanding the differences between a simple container and the GitHub execution environment, I decided to write this tutorial in the hope that it will help others who prefer to write an action in JavaScript.

Environment setup

The basic setup is straightforward – start by following GitHub’s tutorial all the way to the entrypoint.sh section. The main difference up to this point is in the chosen docker image. I suggest using the alpine image, it’s very lightweight compared to the regular node image. In any case, I suggest using an LTS variant, currently being node 10.

A very important tool, one that helped reduce the development cycle from 5 minutes per iteration to mere seconds is Act, a zero-config, easy to use tool to run actions locally. It doesn’t fully replicate the environment (for obvious reasons, it doesn’t provide a GitHub token, more on that later) but it’s close enough to speed up the development process and test your action locally.

At the end of this step, you should have a Dockerfile that looks like this:

Node-specific setup

This is the basic entrypoint.sh file that will work for a Node.js action:

I chose npm ci because it’s the easiest way to make sure you always get the same versions of the packages you want to install. It requires you to have package.json and package-lock.json in your project – but that’s a best practice anyway.

The installation script is in the entry point file and NOT in the Dockerfile (as is usual in classic container use cases) because it makes it much easier to use an npm token and install private packages. All you need to do is add an NPM_TOKEN secret and use it in the entry point file (above npm ci) by adding:

npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
node script.js $* runs the script and passes the action args as arguments to the script.

Node script tips and basic structure

Over the years, I’ve developed a preferred structure for a node executable (CLI) script. I will share it here but for the purpose of this tutorial, this part is completely optional and at this stage, you’re more than ready to develop your own action in Node.js.

The script looks like this:

The important section is at the bottom: if (require.main === module)

It checks if the file was imported/required or if it’s the entrypoint into the program. This allows reusing the same module both programmatically and as a CLI tool.

If this is the entrypoint, I would then parse the command line arguments (using commander) passed in from entrypoint.sh. The arguments were injected into entrypoint.sh by GitHub from the workflow file through the container (more on that later).

I then invoke the main function. Since it’s an async function, I handle its return value with a then clause and handle failure with a catch clause.

It’s also useful to read the event, provided by GitHub, and use it in the script:

const event = JSON.parse(fs.readFileSync('/github/workflow/event.json', 'utf8'))

Secrets, Args, and the execution environment

The Actions environment takes some getting used to. Although GitHub provides great tutorials on all things workflow related, I wanted to mention:

GitHub provides many environment variables inside the container running the Action, but most of the information can also be retrieved from the event file (see section above).
Others are defined in the workflow file, while some are provided as part of the secrets mechanism in GitHub.

Secrets are pretty straightforward, you define them in the repo settings tab and then they’re exposed as environment variables inside the container.

Defining the secret in the repo settings tab:

Using the secret in your workflow file:

The only exception is the GitHub token, which you don’t need to define in the settings. The token is only exposed in the workflow file and GitHub will provide the token itself with these permissions.

Another important item to note is the mounted folder GitHub provides. It’s mounted under /github and provides a couple of useful things:

the event under /github/workflow/event.json and
the repo where the action runs under /github/workspace/REPO_NAME

More information on the mechanics of the mount can be found here.

This tutorial provides a good starting point for anyone who wants to create their first Node.js action. My action can be found here and the code for it here.

If you’re interested in learning more about how you can use Github Actions to automate git workflows, check out this webinar to watch how Shimon Tolts, Datree.io Co-founder, "built a CI/CD dev pipeline with Github Actions, Node.js, Docker, and AWS Fargate".

If you have any questions, corrections, or suggestions please comment below or contact me directly.