Helmwave Tutorial: From Beginner to Advanced

1. Introduction to Helmwave and Its Core Concepts

Helmwave is a modern tool for orchestrating complex Helm deployments, enabling you to manage, templatize, and execute multiple Helm chart releases—in parallel and with high modularity. Unlike vanilla Helm or even Helmfile, Helmwave makes it easy to:

• Define all your Helm releases in one place
• Model dependencies and parallelize deployments
• Share configuration and secrets securely
• Optimize for CI/CD and multi-environment workflows

Key Concepts:

• Helmwave Manifest: helmwave.yml—your main configuration file.
• Release: One Helm chart deployment.
• Values: Configuration (YAML, templated) for each release.
• Dependency Graph: Determines parallelism and ordering.
• Environment Support: Easily target dev, staging, prod, etc.

2. Installation and Setup (Including Prerequisites)

Prerequisites

• Helm 3.x
• kubectl
• Go (if building from source)
• Access to your Kubernetes cluster

Install Helmwave

The easiest way is via prebuilt binaries or Homebrew:

# Using Homebrew (macOS/Linux)
brew install helmwave/tap/helmwave

# Or download the latest release (Linux/macOS/Windows)
curl -sSL https://github.com/helmwave/helmwave/releases/latest/download/helmwave-$(uname -s)-amd64.tar.gz | tar xz
sudo mv helmwave /usr/local/bin/
Code language: PHP (php)

Verify installation:

helmwave --version

3. Explanation of the helmwave.yml Configuration File Structure

The helmwave.yml file is your manifest. Here’s a minimal structure:

# helmwave.yml
project: my-app
releases:
  - name: frontend
    chart: stable/nginx
    namespace: frontend
    values: [frontend-values.yaml]
  - name: backend
    chart: stable/redis
    namespace: backend
    values: [backend-values.yaml]

Sections Explained

• project: Optional project name.
• releases: List of charts (each with name, chart, namespace, values).
• depends_on: (Advanced) Specify dependencies between releases.
• environments: (Advanced) Define multi-env setups.
• templates: Use templates for DRY configs.

4. Creating and Managing Simple Deployments

Step 1: Scaffold your manifest

releases:
  - name: my-nginx
    chart: bitnami/nginx
    namespace: web
    values: [nginx-values.yaml]

Step 2: Prepare your values files

Create nginx-values.yaml as needed.

Step 3: Render and apply

# Build the plan (renders manifests)
helmwave build

# Apply (deploy to your cluster)
helmwave up
Code language: PHP (php)

5. Handling Dependencies Between Releases

You can model dependencies to ensure ordering:

releases:
  - name: database
    chart: bitnami/mysql
    namespace: data
  - name: api
    chart: myorg/api
    namespace: backend
    depends_on:
      - database
Code language: PHP (php)

Result:
api will be deployed after database is ready.

6. Using Environment Variables and Secrets

Helmwave supports SOPS for secrets, and .env files for variables.

releases:
  - name: myapp
    chart: myorg/myapp
    values: [values.yaml, secrets.enc.yaml]   # secrets can be encrypted
Code language: PHP (php)

Using environment variables in values:

# values.yaml
db_password: ${DB_PASSWORD}
Code language: PHP (php)

Load env vars from .env file or your environment:

export DB_PASSWORD=supersecret
helmwave up
Code language: JavaScript (javascript)

7. Parallel and Modular Deployments

Parallel execution is the default—Helmwave will build a dependency graph and deploy releases in parallel where possible.

Modularity:
You can split releases and values into separate files, reuse charts, and compose projects using templates.

releases:
  - name: payment
    chart: myorg/payment
    values: [env/{{ .Environment.Name }}/payment-values.yaml]

8. Advanced Templating and Use of Values

Helmwave supports Go templating in YAML files:

releases:
  - name: "{{ .Values.name }}"
    chart: "{{ .Values.chart }}"
    namespace: "{{ .Values.namespace }}"
    values: ["{{ .Values.valuesFile }}"]
Code language: JavaScript (javascript)

Use a values.yaml for DRY configs and import with --values or reference from environments.

9. Best Practices for Multi-Environment Management

• Use environments:
  Structure your project like this: environments: dev: values: [values-dev.yaml] prod: values: [values-prod.yaml]
• Run per-environment: helmwave --environment dev up helmwave --environment prod up
• Directory layout: helmwave.yml values-dev.yaml values-prod.yaml releases/ frontend-values.yaml backend-values.yaml
• DRY: Use templates and variables as much as possible.

10. Integrating Helmwave into CI/CD Pipelines

Example (GitHub Actions):

- name: Set up Helmwave
  run: |
    curl -sSL https://github.com/helmwave/helmwave/releases/latest/download/helmwave-Linux-amd64.tar.gz | tar xz
    sudo mv helmwave /usr/local/bin/

- name: Deploy with Helmwave
  env:
    KUBECONFIG: ${{ secrets.KUBECONFIG }}
  run: |
    helmwave build
    helmwave up
Code language: JavaScript (javascript)

Tips:

• Store secrets securely (GitHub Secrets, SOPS, etc.)
• Parameterize your pipeline for environments.

11. Debugging, Troubleshooting, and Tips for Optimization

• Use helmwave plan to preview changes before applying.
• Run with increased verbosity: helmwave --log-level debug up
• For failed releases, check Helm logs: helm ls -n <namespace>
• Validate your manifest: helmwave lint
• Use helmwave down to remove all releases managed by your manifest.

12. Real-World Examples and Sample Projects

Sample Project Structure:

my-helmwave-project/
  helmwave.yml
  values-dev.yaml
  values-prod.yaml
  releases/
    nginx-values.yaml
    redis-values.yaml

Example: Microservices Stack

releases:
  - name: users
    chart: myorg/users-service
    namespace: micro
    values: [releases/users-values.yaml]
    depends_on: []
  - name: orders
    chart: myorg/orders-service
    namespace: micro
    values: [releases/orders-values.yaml]
    depends_on: [users]
  - name: payment
    chart: myorg/payment-service
    namespace: micro
    values: [releases/payment-values.yaml]
    depends_on: [orders]

This sets up users first, then orders, then payment—with each using its own values file.

13. Comparison with Similar Tools

• Helmwave: Best for parallel, modular, fast deployments; modern design for CI/CD.
• Helmfile: Most widely used, flexible, simple for most teams.
• Helmsman: Focuses on governance, drift detection, and policy.

Conclusion

Helmwave is a powerful tool for anyone looking to scale, speed up, and organize Helm-based Kubernetes deployments. With built-in support for parallelism, modularity, and multi-environment management, it fits perfectly into modern GitOps and CI/CD workflows.

Additional Resources

• Helmwave GitHub
• Official Documentation
• Helm Chart Hub

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.