Helmfile State Values — Quick Fix Guide

In this tutorial, you'll learn about Helmfile State Values. We cover key concepts, practical examples, and best practices.

The Hook

Helmfile State Values is a critical configuration area in Helmfile-based deployments. When environments aren't defined properly or selectors don't match, releases are silently skipped or deployed with wrong values. Helmfile orchestrates multi-release deployments across different environments but its configuration model has several common pitfalls that trip up even experienced users.

Wrong

The typical misconfiguration is jumping straight into defining releases without setting up environments or understanding how selectors work:

# helmfile.yaml — no environments defined
releases:
  - name: frontend
    chart: stable/nginx
  - name: backend
    chart: stable/app
    labels:
      tier: backend
  - name: redis
    chart: stable/redis
    labels:
      tier: cache

helmfile apply --environment production 2>&1
# Error: no releases found for the specified environment

The error occurs because helmfile requires explicit environment blocks to resolve value files and context. Without them, the apply command doesn't know which configuration to use.

Right

The correct Helmfile configuration defines environments with their value files, applies labels to every release for selective targeting, and uses proper value interpolation:

# helmfile.yaml — with environments and selectors
environments:
  default:
    values:
      - values/default.yaml
  production:
    values:
      - values/production.yaml
      - secrets/production.yaml
    secrets:
      - secrets/production.yaml

releases:
  - name: frontend
    chart: stable/nginx
    labels:
      env: production
      tier: frontend
    values:
      - {{ .Values | toYaml }}

  - name: backend
    chart: stable/app
    labels:
      env: production
      tier: backend
    values:
      - {{ .Values | toYaml }}

  - name: redis
    chart: stable/redis
    labels:
      env: production
      tier: cache
    needs:
      - backend

helmfile template --environment production --selector tier=backend 2>&1
# Renders only the backend release

helmfile apply --environment production 2>&1
# All production releases deployed in dependency order

DodaTech runs helmfile template in CI for every environment before any apply operation reaches production clusters.

Prevention

• Always define environment blocks with corresponding value file paths for each target environment
• Run helmfile template --environment env to preview rendered output before applying
• Apply labels to every release and use --selector for targeted subsets (e.g., canary deployments)
• Commit helmfile.lock to version control for reproducible cross-environment deployments
• Validate YAML syntax with yamllint before running any helmfile command
• Use environment-specific secrets files for sensitive values that differ per environment
• Test environment transitions locally with helmfile template before deploying to production
• Use the needs directive to define release dependency ordering

Common Mistakes with state values

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world HELMFILE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

Q: How does Helmfile resolve value precedence?
A: Values merge in this order: default chart values < environment values < release values < inline values. Later sources override earlier ones, mirroring Helm's own precedence model for consistency.

Q: What is the helmfile.lock file and why should I commit it?
A: The lock file pins chart versions and repository references for all releases, ensuring reproducible deployments across environments and CI/CD runs. Always regenerate it with helmfile deps when dependencies change.

Q: How does DodaTech structure Helmfile configurations for large microservice deployments?
A: We organize Helmfile by environment with separate value files per environment, labeled releases for selective deployment (canary, rolling), and locked dependencies managed via helmfile deps. DodaZIP audits Helmfile configs for consistency across all environments.