helm 101

technical writing
Written By Anne Bertran

This is an adapted version of a blog post I wrote for my engineering team’s documentation. We were starting to adopt Helm as one of our deployment tools, and part of my work was to make it more accessible to developers who were used to a deployment of Java services using Kustomize for configuration.

What is Helm?

Helm is a package management tool for Kubernetes, written in Go. It works in a similar way to Homebrew or Apt, or even like Maven for Java. It provides a way to automate deployment processes and streamline the configuration of sets of Kubernetes resources. In general, Helm tries to reuse as much config definition as possible so the deployment of these resources is as quick and as lightweight as possible.

Helm uses Semantic Versioning for its releases, so it encourages projects to do so too. Helm also gives you a lot of flexibility when configuring Kubernetes resources you might want to deploy, since it allows you to revert changes, see revision history, and edit the configuration files for resources that would typically be statically declared and harder to change once they are created.

Charts

A Chart.yaml file as it is originally generated by the command helm create

A chart is the Helm term for a Kubernetes package. It is a set of files in a directory structure that describes the resources we want to install with Kubernetes. Like a nautical chart, it plots the way a Kubernetes application should be installed.

The main parts of a chart are

  • the Chart.yaml file, which contains metadata about the chart: the chart version, the name and description of the chart, the author of the chart…,

  • the chart’s templates, the set of directives we tell Kubernetes to execute,

  • and potentially also a values.yaml file, where we can specify the default config for each installation of a certain chart. This can be overridden when installing through CLI.

Charts can also reference other charts as dependencies, which helps you reuse existing functionality from charts you might already have. This is done through the Charts folder within a chart.

The structure of a Helm chart directory

We can search for charts on the Artifact Hub, the online registry for Helm charts, or on repositories you might have added to your local system through the command helm add repo. These repositories remain cached on your local system until you update them through the CLI.

If you write a Helm chart, you can package the directory and files into a single .tgz file that can then be easily shared and/or uploaded to a chart repository.

Installations

An installation is a specific instance of a chart in your Kubernetes cluster. This might have been run with specific parameters or values (via the --set flag) that were not originally in the chart definition files, so charts and installations are not the same thing.

Releases

A release is a specific combination of configuration and chart version for an installation. The first installation of a chart is always the first release, but when we upgrade the installation, we are creating a second release, even though it’s the same installation. Rollbacks also count as releases.

The output we get when we deploy an installation. If we run the commands on the NOTES section in the right order, we should obtain the link to our deployed app.

Helm vs. Kustomize

  • While Helm is a package manager, Kustomize is a configuration manager.

  • We have been using Kustomize up until now, which works with a series of declarative templates to standardize configuration in Kubernetes. What Kustomize does is compare these templates to existing Kubernetes YAML manifests, and change/refactor anything that might not match in the manifests.

  • Before Helm v3 came out, Kustomize offered some advantages over Helm, because Helm used to require an extra dependency called Tiller, which was a pod that offered you elevated privileges to change configuration.

  • Kustomize didn’t require Tiller, but now Helm doesn’t either as long as you’re using the most recent version.

  • You can read a more in-depth comparison here.

From chart to deployment: the process

The chart is then read by Kubernetes, using the kubectl tool, and transformed into Kubernetes manifests (a specification of a Kubernetes API object in JSON or YAML format). Kubernetes understands these manifests and turns them into resources.

A list of useful Helm CLI commands

  • helm help: general help text

  • helm version: check version

  • --kube-context: flag that overrides kubernetes configuration context

  • helm repo add [NAME] [URL] [flags]: adds a chart repository

  • helm repo list: shows all the chart repositories installed.

    • can also be used as helm repo remove, update, index, and add

  • helm search repo [KEYWORD]: search the chart repositories for something

  • helm search: search for charts

  • helm pull: download a chart to your local directory to view

  • helm install [INSTALLATION (chart instance) NAME] [REPOSITORY/NAME]: upload the chart to Kubernetes

  • helm list: list releases of charts

  • helm completion: generate autocompletion scripts for the specified shell

  • helm create: create a new chart with the given name

  • helm dependency: manage a chart's dependencies

  • helm env: helm client environment information

  • helm get [notes/values/manifest]: download extended information of a named release

  • helm history: fetch release history

  • helm install: install a chart

  • helm lint: examine a chart for possible issues

  • helm package: package a chart directory into a chart archive

  • helm plugin: install, list, or uninstall Helm plugins

  • helm pull: download a chart from a repository and (optionally) unpack it in local directory

  • helm push: push a chart to remote

  • helm registry: login to or logout from a registry

  • helm rollback: roll back a release to a previous revision

  • helm search: search for a keyword in charts

  • helm show: show information of a chart

  • helm status: display the status of the named release

  • helm template: locally render templates. designed to isolate the template-rendering process of Helm from its installation/upgrade logic

  • helm test: run tests for a release

  • helm uninstall:   uninstall a release

  • helm upgrade: upgrade a release

  • helm verify: verify that a chart at the given path has been signed and is valid

  • helm version: print the client version information

  • --namespace or -n: flag that (followed by the namespace name) identifies which namespace you want to use/work with

Other useful resources

Anne Bertran
Previous

a duet with ghosts - quest design
Next

code review: ideas and best practices