> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm Controller

> Explains how Flux source and Helm controllers fetch and package Helm charts, produce artifacts, and reconcile HelmRelease resources to install, upgrade, test, rollback, and garbage collect releases.

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](https://fluxcd.io/docs/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:

```bash theme={null}
# 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:

```bash theme={null}
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:

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

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

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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

* [Flux - Source Controller](https://fluxcd.io/docs/components/source/)
* [Flux - Helm Controller](https://fluxcd.io/docs/components/helm/controller/)
* [Helm Project](https://helm.sh/)
* [Kubernetes Concepts](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/)

That's all for now.

> **[Watch Video](https://learn.kodekloud.com/user/courses/gitops-with-fluxcd/module/205ec7c7-4cb6-4ecb-9bb5-fa50419f1e68/lesson/e700bfa3-d070-452d-a9c4-7fad1dfcff87)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.