Helm Controller

In this lesson we explain how the Helm controller in Flux works together with the source controller to manage Helm charts and chart artifacts. At a high level:

The source controller fetches Helm charts from different sources (Git repositories, Helm repositories, OCI registries, S3 buckets) and packages them as chart artifacts.
The Helm controller watches Kubernetes HelmRelease custom resources, consumes chart artifacts produced by the source controller, and performs Helm operations (install, upgrade, uninstall, test, rollback) to reconcile the desired release state.

Before you begin, ensure Flux is installed and the Flux controllers are running in the flux-system namespace. See the Flux documentation for installation and prerequisites: Flux - Installation.

Source controller: fetching and packaging charts

The source controller is responsible for pulling charts and producing versioned chart artifacts that other controllers (like the Helm controller) can consume. Typical workflows include:

Fetching multiple charts from a Git repository and packaging them as tar artifacts.
Indexing and packaging charts from a Helm repository (for example, Bitnami) into tar artifacts.
Publishing chart artifacts from OCI registries or object stores.

Example: create a Git source for charts and a HelmRepository source for Bitnami:

# Create a Git source for charts stored in a repository
flux create source git my-helm-charts \
  --url https://github.com/sidd-harth/charts \
  --branch main

# Create a HelmRepository source (example using Bitnami)
flux create source helm bitnami \
  --url https://charts.bitnami.com/bitnami \
  --cert-file ./cert.crt \
  --key-file ./key.crt \
  --ca-file ./ca.crt

You can inspect the artifacts downloaded by the source controller by exec’ing into the source-controller pod and listing the data/ directory:

kubectl -n flux-system exec -it deployment/source-controller -- sh

# Inside the shell
~ $ tree data/
data/
├── gitrepository
│   └── flux-system
│       └── my-helm-charts
│           ├── 1b31558bb1a701c7592652bbc9e3.tar.gz
│           └── latest.tar.gz
└── helmrepository
    └── flux-system
        └── bitnami
            ├── index-e6dc924894f5f871db9b968.yaml
            └── index.yaml

These files show the raw assets the source controller has retrieved and indexed.

Helm controller: reconciling HelmRelease resources

The Helm controller reacts to HelmRelease custom resources. A HelmRelease describes the desired state of a Helm release (which chart, which version, and what values). When a HelmRelease is created or modified, the Helm controller:

Creates a HelmChart object that requests a specific chart and version.
Waits for the source controller to produce the corresponding HelmChart artifact.
Consumes the artifact and runs the Helm operations required to install or upgrade the release.
Optionally runs tests, handles rollbacks, and removes releases when the HelmRelease is deleted.

Example: create a HelmRelease that points to the bitnami HelmRepository:

flux create helmrelease chart-z-release \
  --source HelmRepository/bitnami \
  --chart chart-z \
  --chart-version=1.2.3 \
  --values values.yml

When the HelmRelease is reconciled for the first time, the Helm controller will create a HelmChart resource that asks for the specified chart version. The source controller then produces the HelmChart artifact for the requested chart. Example HelmChart object generated by the source controller:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmChart
metadata:
  name: flux-system-chart-z-release
spec:
  interval: 1m0s
  chart: chart-z
  reconcileStrategy: ChartVersion
  sourceRef:
    kind: HelmRepository
    name: bitnami
  version: '1.2.3'
status:
  artifact:
    path: helmchart/flux-system/flux-system-chart-z-release/chart-z-release-1.2.3.tgz
    revision: 1.2.3
    url: http://source-controller.flux-system.svc.cluster.local/helmchart/flux-system/flux-system-chart-z-release/chart-z-release-1.2.3.tgz

After the artifact is produced you can also observe the helmchart directory under the source controller’s data directory:

kubectl -n flux-system exec -it deployment/source-controller -- sh

# Inside the shell
~ $ tree data/
data/
├── gitrepository
│   └── flux-system
│       └── my-helm-charts
│           ├── 1b31558bb1a701c7592652bbc9e3.tar.gz
│           └── latest.tar.gz
├── helmrepository
│   └── flux-system
│       └── bitnami
│           ├── index-e6dc924894f5f871db9b968.yaml
│           └── index.yaml
└── helmchart
    └── flux-system
        └── flux-system-chart-z-release
            ├── chart-z-release-1.2.3.tgz
            └── latest.tar.gz

The source controller produces versioned chart artifacts (HelmChart). The Helm controller watches HelmRelease objects, looks up the matching HelmChart artifact, and executes Helm operations to reconcile the release to the desired state.

Helm controller responsibilities

Area	What it does	Notes / Examples
Watch & reconcile	Observes `HelmRelease` objects and triggers Helm operations	Installs, upgrades, uninstalls
Artifact consumption	References generated `HelmChart` artifacts produced by the source controller	Consumes tarball at `status.artifact.url`
Chart versioning	Generates `HelmChart` resources to request specific chart versions	`reconcileStrategy: ChartVersion`
Automation	Supports tests, rollbacks, and automatic rollback configuration on failed installs	Configurable in `HelmRelease` spec
Garbage collection	Removes Helm releases when the `HelmRelease` resource is deleted	Ensures cluster state matches desired manifests

Useful links and references

That’s all for now.

GitOps Overview

Flux Overview

Source and Kustomize Controller

Helm Controller and OCI Registry

Image Automation Controller

Secret Management & Sign Verification

Notification Controller

Monitoring & User Interface

Source controller: fetching and packaging charts

Helm controller: reconciling HelmRelease resources

Helm controller responsibilities

Useful links and references

Watch Video

​Source controller: fetching and packaging charts

​Helm controller: reconciling HelmRelease resources

​Helm controller responsibilities

​Useful links and references

Watch Video

Source controller: fetching and packaging charts

Helm controller: reconciling HelmRelease resources

Helm controller responsibilities

Useful links and references