Below is a comprehensive, step-by-step Helmwave tutorial, covering everything from basics to advanced usage. This guide is suitable for both beginners and experienced users, with code samples and practical tips throughout.

Introduction to Helmwave and Core Concepts

Helmwave is a Helm 3-native tool designed to manage and deploy multiple Helm releases across various environments (dev, staging, prod) with a single command. It extends Helm’s functionality by providing:

• Declarative configuration (YAML)
• Parallel deployments
• Dependency management between releases
• Advanced templating (with Sprig and Gomplate)
• Live tracking of resources (via kubedog)
• Separation of environment-specific and shared values
• Integration with external secrets managers

Helmwave is especially powerful for teams practicing GitOps or managing complex, multi-environment Kubernetes deployments.

Installation and Setup

Prerequisites

• Kubernetes cluster (local or remote)
• kubectl configured for your cluster
• Helmwave binary (no need for separate Helm install; Helmwave bundles Helm internally)

Install Helmwave

On macOS:

textbrew install helmwave/tap/helmwave

On Linux:

textexport VERSION=0.38.0
export ARCH=$(uname -m) # amd64, arm64
wget -c https://github.com/helmwave/helmwave/releases/download/v$VERSION/helmwave_${VERSION}_linux_${ARCH}.tar.gz -O - | tar -xz
sudo mv helmwave /usr/local/bin/

Or use your package manager (.deb, .rpm, .apk files available).

Docker:

textdocker run --rm -it ghcr.io/helmwave/helmwave:latest

helmwave.yml Configuration Structure

The helmwave.yml file defines your project’s desired state. Here’s a minimal example:

textproject: QuickStart
version: "0.40.5"

registries:
  - host: registry-1.docker.io

.options: &options
  namespace: my-namespace
  create_namespace: true
  wait: true
  timeout: 1m
  max_history: 3

chart:
  name: oci://registry-1.docker.io/bitnamicharts/nats
  version: 7.8.3

releases:
  - name: a
    <<: *options
  - name: b
    <<: *options

Sections:

• project, version: Metadata
• registries: OCI/Helm chart registries
• .options: YAML anchor for shared release options
• chart: Chart source and version
• releases: List of releases to deploy, each with its own name and options

Creating and Managing Simple Deployments

1. Create helmwave.yml (as above).
2. Build the plan: texthelmwave build This generates a plan in .helmwave/.
3. Deploy: texthelmwave up Output will show each release as it’s deployed: [🙃 aka INFO]: ✅ release: a@my-namespace
   [🙃 aka INFO]: ✅ release: b@my-namespace
4. Verify: texthelm list -n my-namespace kubectl get pods -n my-namespace Both releases should be running.

Handling Dependencies Between Releases

Helmwave lets you control the order of deployments using depends_on:

textreleases:
  - name: db
    namespace: my-namespace
    # ...db options...
  - name: app
    namespace: my-namespace
    depends_on:
      - db@my-namespace
    # ...app options...

• app waits for db to finish before deploying.
• If a dependency is missing, you can mark it as optional to prevent failure.

Using Environment Variables and Secrets

• Environment Variables: Use templating functions like requiredEnv in your values files: textimage: tag: '{{ requiredEnv "IMAGE_TAG" }}' This fails if IMAGE_TAG isn’t set.
• Secrets: Integrate with external sources (e.g., Vault, AWS SSM) using Gomplate functions in your values files or templates.

Parallel and Modular Deployments

• Parallelism: By default, Helmwave deploys releases in parallel unless dependencies are specified.
• Modularization: Use YAML anchors (&options, <<: *options) to DRY your configuration and manage shared/reusable release options.

Advanced Templating and Use of Values

• Templating: Helmwave supports Go templates, Sprig, and Gomplate functions in your YAML and values files.
• Examples:
  • Use toYaml, fromYaml, readFile, and more.
  • Dynamically generate values or pull from external sources.

Best Practices for Multi-Environment Management

• Separate values per environment: Use a directory structure like: textvalues/ dev/ app.yaml staging/ app.yaml prod/ app.yaml
• Template your helmwave.yml or values files to inject environment-specific settings.
• Version control your configuration and values.
• Use tags to group releases by environment or purpose.

Integrating Helmwave into CI/CD Pipelines

Helmwave is designed for CI/CD integration:

GitHub Actions Example:

text- uses: helmwave/setup-action@v0.2.0
  with:
    version: '0.24.0'
- run: helmwave yml
- run: helmwave build
- run: helmwave up

GitLab CI Example:

texthelmwave:
  stage: deploy
  image: ghcr.io/helmwave/helmwave:latest
  script:
    - helmwave yml
    - helmwave build
    - helmwave up

Artifacts and planfiles can be stored for traceability.

Debugging, Troubleshooting, and Optimization Tips

• Live Tracking: Use --kubedog flag for real-time resource tracking.
• Logs: Helmwave outputs detailed logs; increase verbosity with HELMWAVE_LOG_LEVEL=debug.
• Pending Releases: Use pending_release_strategy to automatically handle stuck releases.
• General Kubernetes Debugging: Use helm list, helm status, kubectl logs, and kubectl describe for deeper investigation.
• Optimization: Use YAML anchors, templates, and parallelism to keep configs DRY and deployments fast.

Real-World Examples and Sample Projects

• Official Quick Start:
• Demo Repository:
• Multi-environment Example: Directory structure with separate values for dev, staging, prod.

Comparison: Helmwave vs. Helmfile vs. Helmsman

Feature	Helmwave	Helmfile	Helmsman
Syntax	YAML + sprig/gomplate	YAML + sprig	TOML/YAML
Parallel Deployments	Yes	Yes	Limited
Dependency Management	depends_on	needs	Priority-based
Live Tracking (kubedog)	Yes	No	No
Templating Engines	Sprig, Gomplate	Sprig	None
External Secrets	Via Gomplate	Custom functions	?
Helm Integration	Bundled library	Shell out	Shell out
Planfile Support	Yes	No	No
Multi-environment Support	Strong	Strong	Basic
Docker Image Size	~30MB	~300MB	?

Summary:
Helmwave is a powerful, modern tool for managing complex, multi-environment Kubernetes deployments with Helm. It offers advanced templating, parallelism, dependency management, and seamless integration with CI/CD and secrets management, making it ideal for teams seeking speed, maintainability, and automation in their Kubernetes workflows.

dsdsada