Flux’s HelmRepository source is your gateway to pulling Helm charts into your Kubernetes cluster automatically.
Here’s a HelmRepository definition that points to the bitnami Helm chart repository:
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
name: bitnami
namespace: flux-system
spec:
interval: 5m
url: https://charts.bitnami.com/bitnami
This tells Flux to check the bitnami repository every 5 minutes for updates. Flux will then fetch the index file from this URL and make the available chart information available to other Flux controllers, like HelmRelease.
The core problem Flux solves here is the manual, error-prone process of updating Helm chart dependencies. Instead of running helm repo update and then manually updating your values.yaml or chart versions, Flux handles it. When a HelmRepository is defined, Flux continuously monitors the specified URL. If the repository’s index file changes (indicating new chart versions or updates), Flux detects this. It then synchronizes this information internally, making it available for other Flux custom resources, most notably HelmRelease, to consume.
Internally, Flux maintains a cache of the Helm repository’s index file. It periodically fetches this index file from the url specified in the HelmRepository manifest. The interval field dictates how often this check occurs. When a new version of a chart is published and its entry appears in the index file, Flux updates its cached version of the index. This updated index is then discoverable by HelmRelease resources that reference this HelmRepository source.
The primary lever you control is the url and interval. The url must be the direct endpoint of the Helm repository’s index file. The interval determines the responsiveness of your synchronization; a shorter interval means faster detection of new chart versions but also more frequent network requests to the repository. You can also specify timeout and utenção for more granular control over the fetch operation.
A HelmRepository can also be configured with authentication, such as basic auth or TLS client certificates, if the repository is private. This is done by referencing a Kubernetes Secret containing the necessary credentials within the HelmRepository spec.
When you create a HelmRelease that depends on this HelmRepository, you’ll reference it by name. For example, a HelmRelease might have a chart section like this:
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: wordpress
namespace: default
spec:
interval: 10m
chart:
spec:
chart: wordpress
version: ">=12.0.0 <13.0.0"
sourceRef:
kind: HelmRepository
name: bitnami
namespace: flux-system
values:
# ... your WordPress values
Here, the sourceRef points to the bitnami HelmRepository we defined earlier. Flux will then look for a wordpress chart within the bitnami repository, respecting the version constraint. If a newer version matching the constraint becomes available in the bitnami repository, Flux will automatically update the deployed wordpress release.
The most surprising thing about HelmRepository is that it doesn’t actually store the Helm charts themselves. It only stores and updates the index file that lists available charts and their versions. When a HelmRelease needs to install or upgrade a chart, it uses the information from the HelmRepository’s index to know where to fetch the actual chart archive from, often a different URL than the HelmRepository itself points to.
The next concept you’ll likely encounter is how to manage chart versions within a HelmRelease to leverage the updates detected by your HelmRepository sources.