Helmfile: The Complete Guide

Helmfile is a declarative tool that helps manage and deploy multiple Helm charts in Kubernetes. It simplifies Helm release management by enabling automation, configuration management, and dependency handling for complex deployments.

---

1. What is Helmfile?

Helmfile is an open-source tool that extends Helm by allowing users to manage multiple Helm releases through a single YAML configuration file (helmfile.yaml). It helps with:

• Multi-chart deployments (deploy multiple Helm charts at once)

• Environment-based configurations (stage, prod, dev, etc.)

• Automatic Helm state management (ensuring consistency)

• Secret management (via SOPS, AWS Secrets Manager, etc.)

• CI/CD automation (integrating Helm into DevOps pipelines)

---

2. Why Use Helmfile?

Without Helmfile (Traditional Helm Approach)

• You must manually run:

    helm install <release-name> <chart> --values values.yaml
  

• If deploying multiple charts, you need multiple commands.

• Managing environment-specific values requires separate values.yaml files.

• No built-in dependency management between charts.

With Helmfile

• You define all Helm releases in a single YAML file (helmfile.yaml).

• Deploy, update, or rollback multiple releases with a single command.

• Environments are handled easily.

• Works well with GitOps workflows.

---

3. Helmfile Structure

A basic helmfile.yaml file looks like this:

releases:
  - name: my-app
    namespace: default
    chart: stable/nginx
    version: 1.0.0
    values:
      - values.yaml

• releases: Defines Helm charts to be deployed.

• name: Name of the Helm release.

• namespace: Kubernetes namespace where the release will be deployed.

• chart: Helm chart name (can be local or remote).

• version: Specific Helm chart version.

• values: Specifies Helm values (values.yaml).

---

4. Features of Helmfile

4.1. Managing Multiple Helm Releases

Helmfile allows managing multiple releases at once:

releases:
  - name: frontend
    namespace: web
    chart: ./charts/frontend
    values:
      - frontend-values.yaml

  - name: backend
    namespace: api
    chart: ./charts/backend
    values:
      - backend-values.yaml

You can deploy both frontend and backend apps with a single command.

---

4.2. Using Environments

Helmfile supports environments (environments:) to handle multiple deployments (dev, staging, prod).

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

releases:
  - name: my-app
    namespace: default
    chart: ./charts/my-app
    values:
      - {{ .Environment.Values | first }}

• Deploy in production:

    helmfile -e production apply
  

---

4.3. Helmfile Commands

Example:

helmfile apply

---

4.4. Templating & Variables

Helmfile supports YAML templating for dynamic values.

releases:
  - name: my-app
    namespace: default
    chart: ./charts/my-app
    values:
      - values-{{ .Environment.Name }}.yaml

• Deploy in staging:

    helmfile -e staging apply
  

---

4.5. Managing Secrets

Helmfile integrates with SOPS, AWS Secrets Manager, and other secret managers.

Example using SOPS for Secrets:

secrets:
  - secrets.yaml

releases:
  - name: my-app
    namespace: default
    chart: ./charts/my-app
    values:
      - values.yaml
      - secrets.yaml

Encrypt secrets using SOPS:

sops --encrypt --in-place secrets.yaml

---

4.6. Helmfile Hooks (Pre/Post Deployment)

Helmfile allows hooks to run commands before or after Helm releases.

releases:
  - name: my-app
    namespace: default
    chart: ./charts/my-app
    hooks:
      - events: ["presync"]
        command: "./scripts/pre-deploy.sh"

• presync hook runs before deployment.

• postdeploy hooks can be used for post-processing.

---

4.7. CI/CD Integration

Helmfile works well with GitOps and CI/CD pipelines.

Example: GitHub Actions Workflow

name: Deploy with Helmfile

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v2

      - name: Install Helm & Helmfile
        run: |
          curl -fsSL https://raw.githubusercontent.com/helmfile/helmfile/main/install.sh | bash
          helm version
          helmfile version

      - name: Deploy to Kubernetes
        run: helmfile apply -e production

---

4.8. Helmfile Locking Mechanism

Helmfile ensures reproducibility by supporting Helm chart locking.

helmfile deps

This generates a helmfile.lock file, ensuring the same chart versions are deployed in all environments.

---

5. Helmfile Best Practices

✅ Use Environments: Define separate values.yaml for each environment.
✅ Use Helmfile Diff: Always run helmfile diff before applying changes.
✅ Enable Secrets Management: Use SOPS or AWS Secrets Manager.
✅ Integrate with CI/CD: Automate Helmfile deployments.
✅ Use Locking (helmfile.lock): Ensure consistent Helm versions.

---

6. When Should You NOT Use Helmfile?

🚫 If your deployment consists of only a single Helm chart (Helm alone is sufficient).
🚫 If you don't need multiple environments or chart dependencies.
🚫 If you are using a fully GitOps-based tool like ArgoCD or FluxCD (they handle Helm deployments).

---

7. Helmfile vs. Helm vs. ArgoCD

• Use Helm for simple, single-chart deployments.

• Use Helmfile when managing multiple charts & environments.

• Use ArgoCD for GitOps-style Helm deployments.

---

8. Conclusion

Helmfile is a powerful tool that simplifies Helm deployments by enabling multi-chart management, environment handling, secret management, and CI/CD automation. It is ideal for DevOps teams managing complex Kubernetes applications.