How do HelmRelease resources work in FluxCD for managing Helm chart deployments?

Think of a HelmRelease as a standing order at a restaurant. Instead of manually ordering your meal each time you visit, you set up a standing order (HelmRelease) that specifies the restaurant (HelmRepository), the dish (chart name and version), and your customizations (values). The waiter (helm-controller) automatically brings your order whenever you sit down, and if the kitchen messes up (failed deployment), they bring you the previous version instead (rollback).

A HelmRelease is a custom resource in the helm.toolkit.fluxcd.io API group, managed by the Flux helm-controller. It provides a declarative way to manage Helm chart installations that integrates seamlessly with the GitOps workflow. Instead of running helm install or helm upgrade commands manually, you define a HelmRelease resource in Git, and the helm-controller ensures the cluster matches that definition. The resource specifies which chart to install (name and version), where to find it (a HelmRepository or GitRepository source), which namespace to install into, and what values to pass to the chart.

The helm-controller supports two types of chart sources. A HelmRepository is the most common, pointing to a standard Helm chart repository like Bitnami or a private chart museum. Alternatively, you can reference a GitRepository when the Helm chart lives alongside your application code in a Git repository. In either case, the controller watches for new chart versions according to the specified semver constraint and automatically upgrades when a matching version appears. For example, specifying version: ">=1.0.0 <2.0.0" would automatically upgrade to 1.1.0 or 1.2.0 when released, but not 2.0.0.

Values configuration in a HelmRelease is flexible and supports multiple layers. You can inline values directly in the spec.values field, reference a ConfigMap or Secret using spec.valuesFrom, or combine both with the valuesFrom entries being merged on top of inline values. This layering allows teams to define base values in Git and override environment-specific values through ConfigMaps that are managed separately. The helm-controller also supports post-renderer patches using Kustomize, which lets you modify the rendered Helm output before it is applied, solving the common problem of charts that do not expose enough configuration options.

In production, HelmReleases provide several safety features. The install and upgrade sections support configuring remediation strategies: you can specify how many retries to attempt, whether to rollback on failure, and a timeout for each operation. The test section configures Helm test execution after installation or upgrade, ensuring that the chart's built-in tests pass before the release is considered successful. If an upgrade fails and rollback is enabled, the helm-controller automatically reverts to the previous release version, maintaining application availability. The controller also sets detailed status conditions on the HelmRelease resource, making it easy to monitor release health through flux get helmreleases or Kubernetes monitoring tools.

For teams migrating from imperative Helm usage, adopting HelmReleases is a significant operational improvement. Instead of relying on whoever last ran helm upgrade having the correct values file, the desired state is version-controlled in Git. Every change is auditable, reversible, and reviewable through pull requests. The transition path is straightforward: export your existing release values with helm get values, create a HelmRelease resource with those values, and let Flux adopt the release.