Helmfile Tutorial: From Beginner to Advanced

1. Introduction to Helmfile

What is Helmfile?

Helmfile is an open-source tool that lets you declare, manage, and deploy multiple Helm charts as a unified, version-controlled “desired state” for your Kubernetes clusters.
It addresses the challenge of coordinating several Helm releases, environment variations, and values files with YAML-based configuration and automation.

Why Use Helmfile?

Declarative: Manage all Helm releases in one file.
Templating: Templatize values for different environments.
Idempotency: Ensure your clusters match your defined state.
GitOps-friendly: Store configs in Git for auditable deployments.

Common Use Cases

Managing microservices where each service has its own Helm chart.
Promoting app stacks across dev/staging/prod with environment-specific settings.
Enabling repeatable, auditable, and automated deployments in CI/CD pipelines.

2. Installing and Setting Up Helmfile

Prerequisites

Helm v3.x
kubectl
Kubernetes cluster access (minikube, KIND, EKS, GKE, etc.)

Install Helmfile

Using Homebrew (macOS/Linux):

brew install helmfile

Binary Download (All Platforms):

Download the latest release and move to your PATH.

Check Installation:

helmfile --version

3. Understanding `helmfile.yaml` Structure and Syntax

Minimal Example

# helmfile.yaml
releases:
  - name: nginx
    namespace: web
    chart: bitnami/nginx
    version: 13.2.17
    values:
      - values/nginx-values.yaml

Key Sections

releases: List of Helm releases to deploy.
chart: Chart reference (repo/chartname or local path).
namespace: Kubernetes namespace for the release.
version: Chart version (optional).
values: List of values YAML files.

Other Useful Fields

secrets: Encrypted value files (see secret management).
dependsOn: Set deployment order.
labels: Tag releases for grouping/selectors.
environment: Global and release-level environment overrides.

4. Managing Single and Multiple Helm Releases

Single Release Example

releases:
  - name: redis
    namespace: data
    chart: bitnami/redis
Code language: PHP (php)

Multiple Releases Example

releases:
  - name: backend
    chart: stable/myapp-backend
    namespace: myapp
    values: [values/backend.yaml]
  - name: frontend
    chart: stable/myapp-frontend
    namespace: myapp
    values: [values/frontend.yaml]

Helmfile will install/upgrade both charts in order.

5. Organizing and Templating Values Files (Per-Environment)

Directory Layout

helmfile.yaml
environments/
  dev.yaml
  staging.yaml
  prod.yaml
values/
  backend.yaml
  frontend.yaml

Per-Environment Values

environments:
  dev:
    values:
      - environments/dev.yaml
  prod:
    values:
      - environments/prod.yaml

Run with:

helmfile -e dev apply
helmfile -e prod apply

Templated Values Files

Helmfile supports Go templating:

releases:
  - name: "{{ .Environment.Name }}-backend"
    values:
      - "values/backend-{{ .Environment.Name }}.yaml"
Code language: JavaScript (javascript)

6. Using Environment Variables and Secret Management

Environment Variables

Reference in helmfile.yaml using Go templating:

releases:
  - name: api
    chart: myorg/api
    values:
      - db_password: "{{ requiredEnv "DB_PASSWORD" }}"
Code language: JavaScript (javascript)

Set variables:

export DB_PASSWORD=supersecret
helmfile apply
Code language: JavaScript (javascript)

Secret Management

Use sops to encrypt secrets.
Reference them in your helmfile.yaml:

releases:
  - name: secure-app
    chart: myorg/app
    secrets:
      - secrets/app-secrets.enc.yaml

Helmfile will decrypt at runtime.

7. Handling Dependencies and Release Ordering

`needs`/`dependsOn` Example

releases:
  - name: db
    chart: bitnami/postgresql
    namespace: core
  - name: api
    chart: myorg/api
    namespace: core
    needs:
      - core/db
Code language: PHP (php)

Here, api is deployed only after db is ready.

8. Grouping Releases and Using Selectors

Labeling and Selecting

releases:
  - name: frontend
    labels: { tier: web }
    chart: myorg/frontend
  - name: backend
    labels: { tier: api }
    chart: myorg/backend

Deploy only frontend:

helmfile --selector tier=web apply

9. Advanced Templating Features (Go Templating)

Use Go template expressions almost anywhere:

releases:
  - name: "{{ .Environment.Name }}-{{ .Release.Name }}"
    values:
      - "values/{{ .Release.Name }}-{{ .Environment.Name }}.yaml"
Code language: JavaScript (javascript)

Use {{ env "ENV_VAR" }} for custom environment variables.

Pro Tip:
You can also include other YAML files with {{ readFile "path" }}.

10. Best Practices for Multi-Environment Management

Keep environments in separate files/folders.
Don’t duplicate values: Use templates, environments:, and overlays.
Version lock your charts for reproducibility.
Store secrets encrypted with SOPS or Sealed Secrets.

Example:

environments:
  staging:
    values:
      - environments/staging.yaml
  prod:
    values:
      - environments/prod.yaml

11. Integrating Helmfile into GitOps & CI/CD Pipelines

Sample GitHub Actions Workflow

- name: Install Helmfile
  run: brew install helmfile

- name: Deploy (staging)
  env:
    KUBECONFIG: ${{ secrets.KUBECONFIG }}
  run: |
    helmfile -e staging apply

Store your KUBECONFIG and secrets as CI/CD secrets.
Pin chart and Helmfile versions for consistent builds.

12. Troubleshooting, Debugging, and Optimization

Preview changes: helmfile diff
Verbose/debug logs: helmfile --log-level=debug apply
Dry-run mode: helmfile apply --dry-run
Clean up: helmfile destroy

Common Issues:

Ensure all values/secrets files exist and are correct.
Double-check environment variable usage.
Use helmfile lint to validate configs.

13. Real-World Examples, Sample Configs, and Pro Tips

Sample Microservices Stack

environments:
  dev:
    values: [environments/dev.yaml]
releases:
  - name: users
    chart: myorg/users
    namespace: micro
    values: [values/users.yaml]
  - name: orders
    chart: myorg/orders
    namespace: micro
    values: [values/orders.yaml]
    needs:
      - micro/users

Pro Tips

Store your helmfile.yaml and values in Git for audit and rollback.
Use selectors to deploy/update only what’s needed.
Use dependsOn/needs to manage inter-chart relationships.

14. Comparison with Similar Tools

Feature	Helmfile	Helmsman	Helmwave
Declarative YAML Config	✅	✅	✅
Helm Dependency Handling	✅	✅ (via priority)	✅ (graph-based)
Parallel Execution	🚫 (serial)	🚫	✅
Secrets Management	✅ (SOPS, etc)	✅ (native)	✅ (SOPS)
Drift Detection	🚫	✅	🚫
Policy/RBAC Enforcement	⚠️ (Helm only)	✅	⚠️
Most Used in Community	✅	⚠️	⚠️

Helmfile: Most popular, flexible, and GitOps-centric.
Helmsman: Strong in governance and drift detection.
Helmwave: Great for parallel, modular deployments.

Conclusion

Helmfile is your go-to tool for scalable, declarative, and environment-aware Kubernetes application management with Helm.
It’s beginner-friendly, highly customizable, and fits right into modern GitOps and CI/CD workflows—making Kubernetes app lifecycle management predictable and repeatable.

Want code samples, a live demo, or troubleshooting for your specific use case? Just ask!