↓Skip to main content

Configuring Kubernetes with Helmfile

·5 mins
Table of Contents

Helmfile is a command-line tool for deploying sets of configuration to Kubernetes clusters. You could use Helmfile to manage development Kubernetes clusters on laptops, or as part of a CI process that deploys a configuration to clusters on demand. This means that you can use it as the equivalent of Compose for Kubernetes.

Many administrators use GitOps systems like Flux or Argo CD that run on a cluster and continuously apply a configuration. You can deploy a GitOps system on a cluster with Helmfile, or use it to manage all of the configuration of a cluster.

This article is written for Helmfile 1.1.5 and above.

How It Works #

Helmfile enables you to define a configuration for Kubernetes that includes multiple Helm charts, kustomizations and Kubernetes manifests. This configuration is written in YAML files and support templating. Helmfile can lookup values from a wide range of data sources, because it includes vals and can also use helm-secrets to work with SOPS.

Helmfile uses the Go template package for templating the configuration. It also includes the template functions of the Sprig library and HCL.

Each time that you use Helmfile, it generates a configuration that can be applied to Kubernetes clusters. It can also run the relevant Kubernetes tools on your behalf: Helm and Kustomize to apply the generated configuration. You can specify selectors to generate a configuration that only includes some of the Helm releases. This enables you to develop and apply targeted changes.

Helmfile also support a lockfile for the Helm charts. You specify a version requirement for each Helm chart, and Helmfile will resolve the required version. The versions are written to a lockfile which you can store in version control, just like the lockfile that you would use in programming projects. Renovate supports Helmfile, so that you can use Renovate to help you maintain Kubernetes configurations.

Helmfile is designed to be extremely flexible. Each Helmfile configuration can be one or more files, and you can define multiple environments within the same Helmfile configuration. If you define multiple environments in a Helmfile configuration, you can have a separate lockfile for each environment.

You can always use multiple Helmfile configurations on the same Kubernetes cluster if you wish, since each Helmfile configuration will only affect the resources that it manages.

Quick Examples #

To create a Helmfile configuration, make a directory that contains a file with the name helmfile.yaml.gotmpl. This file is the main configuration file. It can reference other files.

Use the file extension .yaml.gotmpl for the main Helmfile configuration file. Helmfile only applies templating to files that have .gotmpl as part of their file extension.

The simplest Helmfile configuration is a single file that looks like this:

---
repositories:
  - name: prometheus-community
    url: https://prometheus-community.github.io/helm-charts

releases:
  - name: prom-norbac
    namespace: monitoring
    chart: prometheus-community/prometheus
    version: '>27.33.0'
    installed: true
    set:
      - name: rbac.create
        value: false

To use this configuration, ensure that you have set the correct Kubernetes context to access the target cluster, and then run Helmfile commands:

# Generates a lock file for Helm chart versions
helmfile deps

# Shows the differences between the current Helmfile configuration and the configuration of the target cluster
helmfile diff

# Applies the changes between the current Helmfile configuration and the configuration of the target cluster
helmfile apply

The namespace for a release will be automatically created if it does not already exist. Helmfile operations do not delete namespaces.

To update the configuration on the cluster, we change the Helmfile configuration and run helmfile apply again.

To completely remove a release, we set the installed option for the release to false, and run helmfile apply again.

This example configuration defines the values for the Helm chart as part of the block for the release. In most cases, you will create separate files and use templating to provide the values for Helm charts.

The configuration below uses templating, and also has labels for the release definitions. We use labels to scope Helmfile commands.

For examples of configurations that use a directory structure, see my example EKS project. This project uses two Helmfile configurations: helmfile/local/ and helmfile/aws/.

Requirements #

Helmfile itself is a single executable file. It relies on Helm and several Helm plugins. It also uses the kustomize command-line tool, in order to manage Kustomizations.

To install Helmfile on macOS and Linux, you can use Homebrew:

brew install helmfile kustomize

Homebrew will install Helm as a dependency of Helmfile.

Once you have Helmfile, run the init command to add the required plugins to your Helm installation:

helmfile init

Helmfile requires these plugins for Helm:

Enabling Autocompletion #

To enable autocompletion for Helmfile in a shell, use helmfile completion. For example, to add autocompletion for the fish shell, run this command:

helmfile completion fish > ~/.config/fish/completions/helmfile.fish

Helmfile currently provides completion support for Bash, fish and zsh.

Resources #

Videos #