Mastering Helmfile: Streamline Multi‑Chart Deployments Across Environments

When using Helmfile, you first need to understand Helm, the package manager for Kubernetes, and how to develop a Helm chart. Helm is used to deploy multiple charts, separate environments, and manage version control. Helmfile leverages a helmfile.yaml file to manage and maintain many Helm charts, enabling environment segregation and version control. GitHub: https://github.com/helmfile/helmfile

Scenario Description

In public‑cloud or private‑cloud scenarios, a single product may require multiple environment configurations (development, testing, pre‑production, production), each with different database, message‑queue instances, credentials, etc. Maintaining separate files for each environment creates a heavy operational burden and security risks. Converting services into Helm charts and using Helmfile for unified deployment, together with Helm Secrets for encrypted credentials, greatly reduces operational complexity and improves security.

Installation

Helmfile can be installed via binary releases or run inside a Docker container, which is convenient for 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 Introduction

The helmfile.yaml file is the core of Helmfile, used to declare all configurations such as repositories, Helm binary path, default Helm flags, common labels, releases, environments, and nested helmfiles. Below is a concise example (full documentation at https://github.com/roboll/helmfile#configuration):

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

# Path to helm binary
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:
- 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

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

Helmfile Debugging

After arranging the helmfile, you can use the following commands to debug:

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

# View helmfile.yaml
$ cat helmfile.yaml

# Example snippet of helmfile.yaml (environment section omitted for brevity)
... (see above example) ...

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

Installing a Chart

helmfile -e test sync

Updating or Deleting a Specific Chart

Use the --selector flag to target releases by label:

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

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

Viewing Changes

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

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