helmfile

Helmfile Skill

You are an expert in Helmfile, a declarative spec for deploying Helm charts to Kubernetes clusters.

Status

Helmfile v1.0 and v1.1 have been released (May 2025). We recommend upgrading directly to v1.1 if you are still using v0.x. Helmfile supports both Helm 3.x and Helm 4.x.

What is Helmfile

Helmfile is a declarative configuration tool that manages Helm releases. It allows you to:

• Keep a directory of chart value files and maintain changes in version control
• Apply CI/CD to configuration changes
• Periodically sync to avoid skew in environments

Key Features

• Declarative: Write, version-control, apply desired state files
• Modules: Modularize common patterns, distribute via Git, S3
• Versatility: Manage charts, kustomizations, and Kubernetes resource directories
• Patch: JSON/Strategic-Merge Patch resources without forking charts

Configuration Structure

Quick Reference

A helmfile.yaml has these top-level sections:

Basic helmfile.yaml

repositories:
  - name: prometheus-community
    url: https://prometheus-community.github.io/helm-charts

releases:
  - name: prometheus
    namespace: monitoring
    chart: prometheus-community/prometheus
    version: "~19.0"
    values:
      - values.yaml

Repository Configuration

repositories:
  - name: stable
    url: https://charts.helm.sh/stable
  # Git-based repository
  - name: polaris
    url: git+https://github.com/reactiveops/polaris@deploy/helm?ref=master
  # OCI registry with auth
  - name: roboll
    url: roboll.io/charts
    certFile: optional_client_cert
    keyFile: optional_client_key
    username: optional_username
    password: optional_password
    oci: true
    passCredentials: true
    verify: true
    keyring: path/to/keyring.gpg
  # Self-signed certificate
  - name: insecure
    url: https://charts.example.com
    caFile: optional_ca_file

Release Configuration Fields

Helm Defaults

helmDefaults:
  kubeContext: kube-context
  wait: true
  timeout: 600
  createNamespace: true
  force: false
  atomic: true
  cleanupOnFail: false
  verify: false
  keyring: path/to/keyring.gpg
  skipSchemaValidation: false
  waitForJobs: true
  recreatePods: false
  historyMax: 10
  devel: false
  skipDeps: false
  reuseValues: false
  enableDNS: false
  skipCRDs: false
  skipRefresh: false
  forceConflicts: false
  takeOwnership: false
  trackMode: ""
  disableAutoDetectedKubeVersionForDiff: false
  args:
    - "--set k=v"
  diffArgs:
    - "--suppress-secrets"
  syncArgs:
    - "--labels=app.kubernetes.io/managed-by=helmfile"

CLI Commands

Essential Commands

helmfile init                    # Initialize dependencies (helm, plugins)
helmfile sync                    # Sync cluster state (helm upgrade --install)
helmfile apply                   # Apply only when changes detected (diff + sync)
helmfile diff                    # Show differences before applying
helmfile doctor                  # AI-assisted diff analysis (summarize + flag risks)
helmfile destroy                 # Uninstall all releases
helmfile template                # Render manifests locally
helmfile lint                    # Lint charts
helmfile test                    # Run helm tests
helmfile list                    # List releases
helmfile deps                    # Lock dependencies
helmfile repos                   # Add chart repositories
helmfile fetch                   # Fetch charts from state file
helmfile status                  # Retrieve status of releases
helmfile build                   # Build all resources from state file
helmfile write-values            # Write values files (like template but for values)
helmfile unittest                # Unit test charts using helm-unittest plugin
helmfile show-dag                # Show release dependency graph (GROUP, RELEASE, DEPENDENCIES)
helmfile cache                   # Cache management
helmfile create                  # Create a helmfile deployment project scaffold

helmfile doctor runs helmfile diff and asks an OpenAI-compatible LLM to summarize the changes and flag risks (data loss, security, breaking changes, etc). When no LLM is configured (HELMFILE_LLM_API_KEY / HELMFILE_LLM_MODEL), it degrades to plain helmfile diff. Secrets are always redacted before LLM transmission. Supports --llm-base-url / --llm-model / --llm-api-key flags and a llm: block in helmfile.yaml. See helmfile doctor --help for details.

Common Flags

Fetch Command (Air-gapped Environments)

helmfile fetch --output-dir ./charts --write-output

Show DAG

helmfile show-dag

Prints a table with GROUP, RELEASE, and DEPENDENCIES. Releases in the same GROUP are deployed concurrently. GROUP 2 starts only after GROUP 1 completes.

Unit Tests

helmfile unittest                  # Requires helm-unittest plugin

releases:
  - name: my-app
    chart: ./charts/my-app
    values:
      - values.yaml
    unitTests:
      - tests      # Relative to chart dir, /*_test.yaml appended

Templating

Built-in Objects

• .Environment.Name - Current environment name
• .Environment.KubeContext - Environment's kube context
• .Values / .StateValues - Environment values (.StateValues is an alias)
• .Release.Name - Release name
• .Release.Namespace - Release namespace
• .Release.Labels - Release labels
• .Namespace - Target namespace
• .Chart - Chart set via --chart flag
• .HelmfileCommand - The helmfile command being run

Helmfile .Values vs Helm .Values

Helmfile uses the same .Values name as Helm. To distinguish, use .StateValues for Helmfile's values:

app:
  project: {{.Environment.Name}}-{{.StateValues.project}}

{{`
extraEnvVars:
- name: APP_PROJECT
  value: {{.Values.app.project}}
`}}

Template Functions

Values Files Templates

Files ending with .gotmpl are rendered as templates:

# values.yaml.gotmpl
db:
  username: {{ requiredEnv "DB_USERNAME" }}
  password: {{ requiredEnv "DB_PASSWORD" }}

Template Partials

Files matching _*.tpl in the same directory are auto-loaded as helpers:

{{- define "myapp.labels" -}}
app: myapp
env: {{ .Environment.Name }}
{{- end -}}

Environments

Environment Configuration

environments:
  default:
    values:
      - environments/default/values.yaml
      - environments/default/values.hcl
      - myChartVer: 1.0.0-dev
  production:
    values:
      - environments/production/values.yaml
      - myChartVer: 1.0.0
      - vault:
          enabled: false
    secrets:
      - environments/production/secrets.yaml
    kubeContext: prod-cluster
    missingFileHandler: Error

Using Environments

helmfile -e production sync
helmfile --environment staging apply

Conditional Releases

releases:
  - name: monitoring
    installed: {{ eq .Environment.Name "production" }}
    chart: stable/prometheus

Values Merging and Data Flow

Values are merged in this order (lowest to highest priority):

┌─────────────────────────────────────────────────────────────────┐
│                    VALUES MERGING ORDER                         │
├─────────────────────────────────────────────────────────────────┤
│  1. Base files (from `bases:`)                                  │
│  2. Root-level `values:` block (Defaults)                       │
│  3. Environment values (yaml/yaml.gotmpl)                       │
│  4. Environment values (HCL, including HCL secrets)             │
│  5. Environment secrets (non-HCL, decrypted)                    │
│  6. CLI overrides (--state-values-set, --state-values-file)     │
└─────────────────────────────────────────────────────────────────┘

Later values override earlier values at the map level (deep merge). Arrays use smart merging (sparse auto-detection by default).

# CLI overrides (highest priority)
helmfile --state-values-set image.tag=v2.0.0 sync
helmfile --state-values-file overrides.yaml sync

Layering and Inheritance

Bases (Layering)

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

Release Templates

templates:
  default:
    namespace: kube-system
    missingFileHandler: Warn
    values:
      - config/{{`{{ .Release.Name }}`}}/values.yaml

releases:
  - name: app1
    inherit:
      - template: default

Nested Helmfiles

helmfiles:
  - path: releases/myapp/helmfile.yaml
    values:
      - {{ toYaml .Values | nindent 4 }}

Hooks

Hook Events

Hook Configuration

releases:
  - name: myapp
    chart: mychart
    hooks:
      - events: ["prepare", "cleanup"]
        showlogs: true
        command: "echo"
        args: ["{{`{{.Environment.Name}}`}}", "{{`{{.Release.Name}}`}}"]
      - events: ["presync"]
        showlogs: true
        command: "kubectl"
        args: ["apply", "-f", "crds.yaml"]
      - events: ["postsync"]
        showlogs: true
        command: "kubectl"
        args: ["rollout", "status", "deployment/myapp"]

kubectlApply Hook

Alternative to command/args, directly apply manifests:

hooks:
  - events: ["presync"]
    kubectlApply:
      - apiVersion: v1
        kind: ConfigMap
        metadata:
          name: my-config
        data:
          key: value

Advanced Features

Resource Tracking with Kubedog

releases:
  - name: myapp
    chart: ./charts/myapp
    trackMode: kubedog
    trackTimeout: 300
    trackLogs: true
    trackKinds:
      - Deployment
      - StatefulSet
    skipKinds:
      - ConfigMap
    trackResources:
      - kind: Deployment
        name: myapp-deployment
        namespace: default

Track Modes:

Kustomize Integration

Deploy kustomizations as Helm releases:

releases:
  - name: myapp
    chart: ./kustomization-dir
    values:
      - images:
          - name: myapp
            newName: myregistry/myapp
            newTag: v1.0

Strategic Merge Patches

releases:
  - name: raw1
    chart: incubator/raw
    values:
      - resources:
        - apiVersion: v1
          kind: ConfigMap
          metadata:
            name: raw1
          data:
            foo: FOO
    strategicMergePatches:
      - apiVersion: v1
        kind: ConfigMap
        metadata:
          name: raw1
        data:
          bar: BAR

JSON Patches

releases:
  - name: myapp
    chart: mychart
    jsonPatches:
      - target:
          version: v1
          kind: ConfigMap
          name: myconfig
        patch:
          - op: remove
            path: /data/old-key

Transformers

releases:
  - name: app
    chart: mychart
    transformers:
      - apiVersion: builtin
        kind: LabelTransformer
        labels:
          env: production
        fieldSpecs:
          - path: metadata/labels
            create: true

Chart Dependencies

Add dependencies without forking:

releases:
  - name: foo
    chart: ./charts/foo
    dependencies:
      - chart: stable/envoy
        version: 1.5
        alias: sidecar

Remote Secrets (vals)

# Single key
releases:
  - name: app
    values:
      - db:
          password: {{ .Values.db.password | fetchSecretValue | quote }}

# Multiple keys
environments:
  default:
    values:
      - service:
          password: ref+vault://svc/#pass
          login: ref+vault://svc/#login

# values.yaml.gotmpl
service:
{{ .Values.service | expandSecretRefs | toYaml | nindent 2 }}

Supported backends: Vault, AWS SSM, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, and more via vals.

Best Practices

Directory Structure

.
├── helmfile.yaml
├── environments/
│   ├── default/
│   │   └── values.yaml
│   └── production/
│       ├── values.yaml
│       └── secrets.yaml
├── releases/
│   └── myapp/
│       └── helmfile.yaml
└── charts/
    └── mychart/

DRY Configuration

1. Use templates for repeated release patterns
2. Use bases for shared configuration
3. Use environments for environment-specific values
4. Use .gotmpl files for templated values
5. Use _*.tpl partials for shared template logic

Missing Keys Handling

# Fail on missing key
{{ .Values.key }}

# Allow missing with default
{{ .Values | get "key" "default" }}

Labels for Filtering

commonLabels:
  team: platform

releases:
  - name: app1
    labels:
      tier: frontend
  - name: app2
    labels:
      tier: backend

helmfile -l tier=frontend sync
helmfile -l team=platform,tier=backend apply

Common Patterns

Multi-environment Setup

environments:
  development:
    values:
      - replicas: 1
        resources: small
  production:
    values:
      - replicas: 3
        resources: large

releases:
  - name: myapp
    chart: mychart
    values:
      - replicaCount: {{ .Values.replicas }}

OCI Charts

repositories:
  - name: ghcr
    url: ghcr.io/myorg/charts
    oci: true

releases:
  - name: myapp
    chart: ghcr/myapp
    version: 1.0.0

Troubleshooting

Debug Template Rendering

helmfile build
helmfile template --debug

Check Release Status

helmfile status
helmfile list

Common Issues

1. Missing env vars: Use requiredEnv for required variables
2. Chart not found: Run helmfile deps or check repository config
3. Diff plugin missing: Install with helm plugin install https://github.com/databus23/helm-diff
4. Secrets not decrypting: Install helm-secrets plugin
5. Helm v4 compatibility: Use trackMode: helm-legacy for charts with broken livenessProbe configs

Environment Variables

When to Use This Skill

Invoke this skill when:

• Creating or modifying helmfile.yaml configurations
• Setting up multi-environment deployments
• Working with release templates and layering
• Integrating Kustomize with Helmfile
• Troubleshooting Helmfile deployment issues
• Implementing best practices for Helm chart management
• Configuring remote secrets with vals
• Using advanced features like strategic merge patches and transformers
• Setting up resource tracking with kubedog
• Managing Helm 4 compatibility
• Writing hooks for lifecycle management