Multi-Environment Values

One chart, many environments — values layering, Helmfile, and secret management

• Values layering with -f flags — later files override earlier
• Environment-specific values files: dev, staging, prod
• Helmfile for declarative multi-environment management
• Secret management: SOPS, helm-secrets, CI injection
• Directory structure patterns for real-world projects

Values Layering

Helm merges multiple -f files left to right. Later files override earlier ones at every key level.

# Base values + environment overlay
helm install myapp ./mychart \
  -f values/base.yaml \
  -f values/prod.yaml

# Three-layer pattern: base → env → region
helm upgrade myapp ./mychart \
  -f values/base.yaml \
  -f values/prod.yaml \
  -f values/prod-us-east.yaml

What Changes Per Environment?

replicaCount: 1
image:
  repository: myapp
  tag: latest
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: false
featureFlags:
  betaSearch: false
  newCheckout: false

replicaCount: 3
image:
  tag: "v2.4.1"
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi
ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths: ["/"]
featureFlags:
  newCheckout: true

Common environment deltas: replicas, resources, ingress hosts, image tags, feature flags, and log levels.

Directory Structure Patterns

mychart/
  Chart.yaml
  values.yaml          # defaults
  values-dev.yaml
  values-staging.yaml
  values-prod.yaml
  templates/

deploy/
  charts/
    mychart/
  values/
    base.yaml
    envs/
      dev.yaml
      staging.yaml
      prod.yaml
    regions/
      us-east.yaml
      eu-west.yaml
  helmfile.yaml

Helmfile: Declarative Multi-Environment

Helmfile wraps Helm with environment-aware, declarative release management.

# helmfile.yaml
repositories:
  - name: bitnami
    url: https://charts.bitnami.com/bitnami

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

releases:
  - name: myapp
    chart: ./charts/mychart
    namespace: {{ .Values.namespace }}
    values:
      - values/base.yaml
      - values/envs/{{ .Environment.Name }}.yaml

Secret Management in Multi-Env

Option 1: CI Injection with --set

# Inject from CI environment variables (never committed to Git)
helm upgrade myapp ./mychart \
  -f values/base.yaml \
  -f values/prod.yaml \
  --set secrets.dbPassword="${DB_PASSWORD}" \
  --set secrets.apiKey="${API_KEY}"

Option 2: helm-secrets + SOPS

# Install the plugin
helm plugin install https://github.com/jkroepke/helm-secrets

# Encrypt a values file with age
sops --encrypt --age $(cat key.pub) values/prod-secrets.yaml > values/prod-secrets.enc.yaml

# Use encrypted file transparently
helm secrets upgrade myapp ./mychart \
  -f values/base.yaml \
  -f values/prod.yaml \
  -f values/prod-secrets.enc.yaml

Kustomize + Helm Comparison

Both tools solve multi-environment configuration, but with different philosophies.

Key Takeaways

1. Single chart, multiple values files — keep environment differences in values, not in templates
2. Layer values left to right — base → environment → region/cluster → secrets
3. Helmfile orchestrates multi-release, multi-env deployments declaratively
4. Secrets belong in vaults, not in Git — use SOPS, helm-secrets, or CI injection
5. CI pipeline per environment — same chart artifact, different values file per stage