Flux HelmRelease: Declarative Helm Charts in Git

Why it exists

Helm is a great package manager for Kubernetes, but running helm commands manually is imperative and doesn't fit the declarative GitOps model. The HelmRelease custom resource was created to bridge this gap, allowing you to define the desired state of a Helm deployment in a manifest that can be version-controlled in Git.

The mental model

Think of a HelmRelease as a recipe for a Helm deployment. It's a Kubernetes Custom Resource (CRD) that tells the Flux Helm Controller everything it needs to know: which chart to use (from which HelmRepository source), what version, which namespace to deploy into, and what configuration values (values.yaml) to apply. You commit this recipe to Git, and Flux's controller acts as the chef, continuously ensuring the deployed release in the cluster matches the recipe in Git.

How it works

The Flux Helm Controller continuously watches for HelmRelease objects in the cluster. When it finds one, it first looks for the corresponding HelmRepository source to find the chart's location. It then fetches the specified Helm chart, combines it with the values from the HelmRelease manifest, and performs the equivalent of a helm install or helm upgrade. Flux periodically re-scans for changes in both the Git repository (for the HelmRelease manifest) and the Helm repository (for new chart versions), automatically applying updates to keep the cluster in sync.

When to use it

Use HelmRelease whenever you want to manage a Helm-packaged application using GitOps. It is the standard way to deploy and configure third-party software like Prometheus, cert-manager, or NGINX Ingress from public chart repositories. It's also ideal for managing your own applications across different environments (dev, staging, prod) with environment-specific configurations stored in Git.

When not to use it

If you are not using Helm to package your applications, HelmRelease is the wrong tool. For deploying raw Kubernetes manifests or Kustomize overlays, you should use Flux's Kustomization resource instead. It may also be overkill for simple, one-off test deployments where you don't need the full GitOps lifecycle management.

One canonical example

To deploy Prometheus, you first define a HelmRepository manifest in Git that points to the prometheus-community chart repository URL. Then, you create a HelmRelease manifest that references that repository, specifies the chart name (kube-prometheus-stack), a chart version, and a values block to configure things like storage persistence and Grafana dashboards. Once committed, Flux will automatically deploy and manage the entire Prometheus monitoring stack.