↓Skip to main content

Configuring Kubernetes with Helmfile

·7 mins
Table of Contents

Helmfile is a command-line tool for describing and applying configurations to Kubernetes clusters. It enables you to define sets of configuration for Kubernetes that each include multiple Helm charts, kustomizations and manifests. Helmfile supports templating in the configuration and lookups that can query local or remote data sources, such as secrets storage, configuration services and external files.

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

Helmfile is particularly useful for clusters that are temporary or should change rapidly as part of another process. For example, you might use it to configure development Kubernetes clusters on laptops, or in a CI pipeline that deploys test clusters on demand.

This article is written for Helmfile 1.1 and above.

How It Works #

Each Helmfile configuration consists of one of more YAML files that describe a set of Helm releases. These YAML files can include templating and lookups. You can define multiple environments within the same Helmfile configuration, to provide different sets of values and for use in conditions.

There is a published YAML schema for Helmfile configuration, so that you can validate your configuration files with standard tools.

Helmfile is designed to build on other existing tools and services as much as possible. It runs Helm to work with Helm releases and Kustomize for kustomizations. The templating uses the standard Go template package with functions from the Sprig library and HCL. Helmfile includes the vals package to lookup values from a wide range of data sources, and it works with SOPS by using the Helm plugin for secrets.

Helmfile will use Helm charts from either remote repositories or the filesystem. It can also maintain lockfiles for the Helm charts from repositories. If you specify a version constraint for a chart in the configuration then Helmfile can resolve the exact version that is required for that chart. It writes these to a lockfile which you can store in version control. This ensures that the same versions are used consistently.

If you define more than one environment in a Helmfile configuration, you should have a separate lockfile for each environment.

When you run Helmfile, it generates the YAML for Helm releases from the configuration and the lockfile, using templating and lookups to resolve values as needed. It only applies this generated configuration if you run the specific commands that change the state of the target cluster. This means that you can develop a configuration and compare it with the deployed releases on a target cluster without making any changes to the current state of that cluster.

You can also develop and apply limited changes by specifying selectors. To use selectors, ensure that your Helmfile configuration has labels for release definitions and included files. You can then specify one or more selectors with any Helmfile command and it will use the labels to determine which parts of the configuration should be used. The generated YAML will only include the required releases.

If you need to deploy Kubernetes manifests that are not part of a Helm chart then you can specify a directory as the source for a release, instead of the location of a Helm chart. The directory only needs to contain YAML files for the manifests and any kustomizations that you want to apply to them. Helmfile will automatically create a temporary Helm chart for the directory and generate a release for it, alongside the Helm releases that it generates for existing charts.

You can use a combination of Helmfile and other tools to manage different resources on the same cluster. Since Helmfile runs Helm and produces standard Helm releases, it is compatible with other Kubernetes management tools.

If you would like to use Helmfile and Argo CD on the same Kubernetes clusters, see the Helmfile documentation on Argo CD integration.

Quick Examples #

To create a Helmfile configuration, make a directory that contains a file with the name helmfile.yaml.gotmpl and add some configuration to the file. The simplest Helmfile configuration 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

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.

Use the file extension .yaml.gotmpl for the main Helmfile configuration file, and any other files with templated values. Helmfile only applies templating to files that have .gotmpl as part of their file extension.

To use a Helmfile configuration, ensure that you have set the correct Kubernetes context to access the target cluster, and change your working directory to the directory for the main file. Then run Helmfile commands:

# Generate a lock file for Helm chart versions
helmfile deps

# Show the differences between the Helmfile configuration and the target cluster
helmfile diff

# Apply the changes between the Helmfile configuration and the target cluster
helmfile apply

When you run 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, change the Helmfile configuration and run helmfile apply again. We should use apply for most deployments. If you need to force Helm to reconcile the releases on the cluster with the configuration, use sync instead:

helmfile sync

To see the complete set of YAML that Helmfile generates, rather than a diff between the generated YAML and the target cluster, use helmfile template:

helmfile template

Add --debug to get more information about how Helmfile generates the YAML, with warnings and error messages for any issues:

helmfile template --debug

To remove a specific release, set the installed option for the release definition to false, and run helmfile apply. To delete all of the releases from a cluster, use destroy:

helmfile destroy

Deleting a Helm release removes all of the resources that it manages. Helmfile will not delete namespaces.

Other Examples of Helmfile Configurations #

For examples of configurations that use a directory structure, see my example EKS project. This project uses three Helmfile configurations:

  • helmfile/aws/ - AWS EKS Auto Mode
  • helmfile/kind/ - Docker Desktop (Kubernetes in Docker)
  • helmfile/minikube/ - Minikube

This project also includes a Task file for standard Helmfile tasks.

Requirements #

Helmfile itself is a single executable file. It relies on Helm and several Helm plugins. It also uses the kustomize command-line tool when working with kustomizations. This means that both Helm and Kustomize must be installed on the system.

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, use init to add the required plugins to your Helm installation. Run this command in a terminal window:

helmfile init

Helmfile uses these plugins for Helm: diff, helm-git, s3 and secrets.

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 #

Documentation #

Tutorials #

Videos #