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.

Source

Emitted as its own document above the HelmRelease. A HelmRelease whose source is missing never resolves a chart, and says so nowhere obvious.

Source kind

Source name

Source namespace Where the source object lives. This is the namespace sourceRef has to name, and the one people leave out.

URL An oci:// URL on a HelmRepository also needs type: oci, which is added for you.

Branch A branch tracks its tip, so what is deployed changes when somebody merges.

Tag or semver range Goes in ref.tag, or ref.semver when it is a range. It does not go on the end of the URL.

Source interval How often the index or the git repository is re-fetched. A chart version missing from the cached index cannot be selected.

HelmRelease

Name

Namespace Where the HelmRelease object lives. It is also the default for sourceRef.namespace, targetNamespace, storageNamespace and dependsOn.

Chart name, or path in the git repository

Chart version A semver range, so this release can upgrade itself with no git change. An exact version is the reproducible choice.

Reconcile interval How often the release itself is reconciled: values re-applied, drift checked, state compared.

Chart interval How often the source is checked for a new chart version. A different clock from the one above.

Write the source namespace into sourceRef

Left out, it defaults to this HelmRelease's namespace, so a source in flux-system is never found.

Namespaces

Three different namespaces can appear on one HelmRelease, and only one of them is where the object lives.

targetNamespace Where the chart's resources are created. Setting this also changes the Helm release name to targetNamespace-name.

storageNamespace Where Flux keeps the Helm release Secret. It does not follow targetNamespace.

Create the target namespace on install

Without it the install fails outright when the namespace is absent.

Failure handling

All of this is off by default. A HelmRelease with no remediation retries a failing upgrade forever and stays failed in between.

install.remediation.retries Failed installs are remediated by uninstalling, then retried. -1 means no limit.

upgrade.remediation.retries 0, the default, means a failed upgrade is left failed.

upgrade.remediation.strategy rollback needs a previous release to exist. There is none when the first install is the thing that failed.

driftDetection.mode Flux's equivalent of Argo CD selfHeal. Off unless you turn it on.

suspend: true

Stops reconciliation. A suspended release keeps its last Ready condition, so most dashboards show it as healthy.

Values and ordering

Inline values One key=value per line. Dots nest, the same as helm --set. Escape a literal dot as \.

valuesFrom Kind/name per line, ConfigMap or Secret. Editing one of these does not trigger a reconcile on its own.

dependsOn Other HelmReleases that must be Ready first, as name or namespace/name. Helm has no ordering of its own.

helmrelease.yaml

updates as you type

Common 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 ready

Two 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 that

version 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.

Related kubernetes tools

Kubernetes YAML Generator Answer a few questions, get a manifest Kubernetes Deployment Generator See the capacity dip before you deploy Kubernetes Service Generator port, targetPort, and which one you meant Kubernetes StatefulSet Generator Stable names, and volumes that outlive you Kubernetes imagePullSecret Generator The registry URL nobody gets right Kubernetes cert-manager Certificates Issuer scope, and the rate limit that costs a week

All 55 kubernetes tools

Elsewhere on the site

Terraform Validator & Formatter AWS IAM Policy Validator & Analyzer Docker Container Image Reference Parser VPC Subnet & CIDR Calculator