Mastering Helmfile: Simplify Multi‑Environment Kubernetes Deployments

Overview

When using Helmfile, you first need to understand Helm and how to develop a Helm chart.

Helm is the package manager for Kubernetes. In real‑world scenarios we often need to deploy multiple charts, differentiate environments, and manage version control. Helmfile addresses these needs.

Helmfile uses a helmfile.yaml file to help users manage and maintain multiple Helm charts, allowing environment separation and version control.

GitHub repository: https://github.com/roboll/helmfile

Scenario Description

In public‑cloud or private‑cloud deployments, a single product may involve many environment‑specific configurations such as database addresses, message‑queue endpoints, and credentials. Maintaining separate configuration files for development, testing, pre‑production, and production greatly increases operational complexity and security risk.

To meet these requirements, we can package each service as a Helm chart, differentiate environments, and use Helmfile for unified deployment management. Sensitive credentials can be encrypted with helm‑secrets, reducing operational burden and improving security.

Installation

Helmfile offers several installation methods; see the releases page for details: https://github.com/roboll/helmfile/releases

Helmfile can also run inside a container, making it easy to integrate into CI/CD pipelines:

# helm 2
$ docker run --rm --net=host -v "${HOME}/.kube:/root/.kube" -v "${HOME}/.helm:/root/.helm" -v "${PWD}:/wd" --workdir /wd quay.io/roboll/helmfile:v0.135.0 helmfile sync

# helm 3
$ docker run --rm --net=host -v "${HOME}/.kube:/root/.kube" -v "${HOME}/.config/helm:/root/.config/helm" -v "${PWD}:/wd" --workdir /wd quay.io/roboll/helmfile:helm3-v0.135.0 helmfile sync

helmfile.yaml Overview

The helmfile.yaml file is the core configuration for Helmfile. It declares repositories, Helm binary path, default settings, common labels, releases, nested helmfiles, environments, and bases.

# Repository configuration
repositories:
- name: <repo-name>
  # url: repo url
  # certFile: certificate file
  # keyFile: key file
  # username: user
  # password: pass

helmBinary: path/to/helm3

helmDefaults:
  tillerNamespace: tiller-namespace
  tillerless: false
  kubeContext: kube-context
  cleanupOnFail: false
  args:
    - "--set k=v"
  verify: true
  wait: true
  timeout: 600
  recreatePods: true
  force: false
  createNamespace: true

commonLabels:
  hello: world

releases:
  # Remote chart example
  - name: vault
    namespace: vault
    createNamespace: true
    labels:
      foo: bar
    chart: roboll/vault-secret-manager
    version: ~1.24.1
    condition: vault.enabled
    missingFileHandler: Warn
    values:
      - vault.yaml
      - address: https://vault.example.com
      - image:
          tag: {{ requiredEnv "IMAGE_TAG" | quote }}
      - db:
          username: {{ requiredEnv "DB_USERNAME" }}
          password: {{ requiredEnv "DB_PASSWORD" }}
      - proxy:
          domain: {{ requiredEnv "PLATFORM_ID" }}.my-domain.com
          scheme: {{ env "SCHEME" | default "https" }}
    set:
      - name: foo.config
        file: path/to/file
      - name: bar[0]
        values:
          - 1
          - 2
      - name: namespace
        value: {{ .Namespace }}

  # Local chart example
  - name: grafana
    namespace: another
    chart: ../my-charts/grafana
    values:
      - "../../my-values/grafana/values.yaml"
      - ./values/{{ requiredEnv "PLATFORM_ENV" }}/config.yaml
    wait: true

helmfiles:
- path: path/to/subhelmfile.yaml
  selectors:
    - name=prometheus
  values:
    - additional.values.yaml
    - key1: val1
- path: git::https://github.com/cloudposse/helmfiles.git@releases/kiam.yaml?ref=0.40.0
  missingFileHandler: Error

environments:
  default:
    values:
      - environments/default/values.yaml
      - myChartVer: 1.0.0-dev
  production:
    values:
      - environment/production/values.yaml
      - myChartVer: 1.0.0
    vault:
      enabled: false
    secrets:
      - environment/production/secrets.yaml
    missingFileHandler: Error

bases:
- environments.yaml
- defaults.yaml
- templates.yaml

apiVersions:
- example/v1

Debugging helmfile

After arranging the helmfile, you can debug with the following commands:

# List directory structure
$ ls
README.org    environments  helm          helmfile      helmfile.yaml releases

# View helmfile.yaml
$ cat helmfile.yaml
... (contents omitted for brevity) ...

# Render templates for a specific environment
$ helmfile -e test template

Installing a Chart

helmfile -e test sync

Updating or Deleting a Chart with helmfile

You can update or delete a release by specifying a label selector:

# Update the web service
helmfile -e test --selector app=web sync

# Delete the web service
helmfile -e test --selector app=web delete

Viewing Changes

Use the diff command to see what would change:

# Show full diff
helmfile -e test --selector app=web diff

# Show diff with limited context
helmfile -e test --selector app=web diff --context 4