Kubernetes Flux HelmRelease Generator
Build a Flux HelmRelease together with the source it needs, because one without the other does nothing. The namespace rules, the two reconcile clocks, the semver range and the remediation defaults are all explained beside the output.
helmrelease.yaml
updates as you typeCommon mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Creating a HelmRelease with no HelmRepository
The release references a source that must exist as its own resource. Without it the HelmRelease sits not-ready with a message about the chart source.
Instead:Create the HelmRepository or GitRepository first, in the namespace the release expects.
Leaving the interval very short
Every interval polls the source, and on a busy cluster with many releases that is real load and real rate-limit pressure on the upstream repository.
Instead:Minutes, not seconds, unless something genuinely needs it.
Assuming a values change triggers a release
Flux reconciles on the interval or on a source change. A ConfigMap referenced through valuesFrom changing does not necessarily trigger one immediately.
Instead:Annotate for reconciliation, or accept the interval.
What breaks a Flux HelmRelease, and why none of it looks broken
A HelmRelease is short and it depends on a second object that is usually written by somebody else, in a different namespace, months earlier. Most of the ways it fails produce a condition on an object nobody is looking at rather than an error anyone sees, so the symptom is that a deploy did not happen and nothing says why.
sourceRef.namespace defaults to the HelmRelease's namespace
The source is almost always in flux-system. The HelmRelease is almost never in flux-system. Leave the namespace out of sourceRef and it resolves against the HelmRelease's own namespace, finds nothing, and reports a missing source rather than a missing namespace. Every name in the file is correct, which is why this one takes so long to spot.
# HelmRepository: namespace flux-system
# HelmRelease: namespace apps
spec:
chart:
spec:
sourceRef:
kind: HelmRepository
name: podinfo
# no namespace -> looked up in "apps"
# -> not found
namespace: flux-system <- the fix
# kubectl describe helmrelease podinfo -n apps
# HelmChart 'apps/apps-podinfo' is not readyTwo intervals, and they are not the same clock
spec.interval is how often the release is reconciled: values re-applied, drift looked at, state compared. chart.spec.interval is how often the source is checked for a chart version matching the range. With an HTTP HelmRepository there is a third one, the repository's own interval, which is how often index.yaml is re-fetched. A version that is not in the cached index cannot be chosen however short the chart interval is.
HelmRepository.spec.interval: 1h
-> index.yaml re-fetched hourly
HelmRelease.spec.chart.spec.interval: 5m
-> version re-resolved against that index
HelmRelease.spec.interval: 10m
-> the release itself reconciled
# new chart published at 12:01
# visible to Flux: 13:00 at the earliest
# upgraded: the next reconcile after thatversion is a range, so a release can upgrade itself
chart.spec.version is a semver expression, not a version. Anything the source publishes that satisfies it is installed on the next chart reconcile, with no commit, no review and no record in git of what changed. Omit the field and the default is *. This is the intended behaviour for a development environment and it is how a production chart moves two minor versions overnight.
version: ">=6.0.0" any 6.x, 7.x, 8.x as published
version: "6.x" any 6.x
version: "~6.9.0" 6.9.x only
version: "6.9.2" this chart, and only this chart
# for a chart from a GitRepository the field is
# ignored entirely: the chart is whatever the branch
# contains, and reconcileStrategy decides whether a
# commit that leaves Chart.yaml alone is even noticed.Without remediation, a failed upgrade stays failed forever
install.remediation.retries and upgrade.remediation.retries both default to 0. A failed upgrade is not rolled back and not retried differently: the release stays failed and helm-controller attempts the same upgrade on every interval indefinitely. Setting a rollback strategy needs a previous successful release to return to, which does not exist when the failure was the first install.
upgrade:
remediation:
retries: 3
strategy: rollback # or uninstall
# strategy: rollback
# needs a stored previous revision, capped by
# maxHistory (default 5)
# strategy: uninstall
# removes the release, and its PVCs with it
# retries: 0 (the default)
# failed, retried, failed, retried, ...Three namespaces on one object, and drift detection is off
metadata.namespace is where the HelmRelease lives. targetNamespace is where the chart's resources go, and setting it renames the Helm release to targetNamespace-name unless releaseName is set. storageNamespace is where the release Secret is kept, and it does not follow targetNamespace. Separately, driftDetection is disabled by default, which is Flux's equivalent of Argo CD selfHeal: a manual edit to a chart-installed resource is neither reverted nor reported.
metadata:
namespace: apps <- kubectl -n apps
spec:
targetNamespace: prod <- resources land here
storageNamespace: apps <- sh.helm.release.v1...
driftDetection:
mode: enabled <- not the default
# deleting the release Secret by hand orphans
# everything the chart installed: helm-controller
# sees no release, installs, and fails on objects
# that already exist.