Flux 2.8 and Helm v4: The GitOps Upgrade Guide
~7 min read
DevOpsKubernetesfluxhelmgitopskuberneteskstatusssacosignkustomize
Save products you love by clicking the heart icon.
Comprehensive guide to testing Stripe payment integrations — test cards, webhook simulation, checkout flows, edge cases, and CI/CD strategies for bulletproof payment systems.
How three independent bugs — a missing LDAP EQUALITY rule, an invisible disabled filter, and a misconfigured OIDC role driver — stacked to block every OpenCloud login, and what it took to find them.
Flux v2.8.0 reached GA on February 24, 2026 — the most significant feature release since Flux v2.0. It ships Helm v4 support, bringing server-side apply and kstatus-based health checking to Helm releases. Helm v4.0.0 itself went GA in November 2025, a major version with breaking changes to the CLI, the plugin system, and post-renderers.
Two converging changes matter if you run GitOps in production:
combined, which breaks real workloads (more below)This guide walks through what changed, what breaks, and how to migrate without drama.
| Feature | Impact |
|---|---|
| Helm v4 support | Server-side apply + kstatus health checks for HelmReleases |
| CEL health checks (HelmRelease) | Custom readiness evaluation for CRDs |
.status.inventory | Inventory of managed resources in HelmRelease status |
CancelHealthCheckOnNewRevision | Reduced mean time to recovery (MTTR) |
| Cosign v3 support | Verify OCI artifacts and container images |
| ArtifactGenerator | Extract and modify Helm charts from tarballs |
| Custom SSA apply stages | Order resource application in kustomize-controller |
| PR comments from notifications | Flux can comment on Pull Requests directly |
UseHelm3Defaults feature gate | Restore Helm v3 behavior across the board |
Helm v4 implements post-renderers as plugins. You can no longer pass an executable directly to helm render --post-renderer — a plugin name must be given. Any existing post-renderer workflow needs a plugin wrapper.
combinedThis is the breaking change most likely to bite you. In Helm 4, hooks are now merged into the YAML stream passed to post-renderers. A post-renderer like Kustomize — which does not allow multiple objects with the same fully-qualified name — fails when a chart redeclares e.g. an RBAC resource used by a pre-install hook that also appears in the regular templates.
Helm 4 defines three strategies:
| Strategy | Behavior | Use case |
|---|---|---|
combined (default) | Hooks + templates in one stream | No post-renderer, or one that tolerates duplicates |
separate | Hooks and templates post-rendered in independent invocations | Post-renderers that de-duplicate by identity (Kustomize) |
nohooks | Hooks untouched, only templates post-rendered | Helm 3 behavior — Kustomize patches against template-only resources |
apiVersion: v2 (the vast majority of today's charts) continue to install and upgradeFlux now ships with Helm v4, and two things change by default:
For teams that prefer Helm v3's behavior across the board, the UseHelm3Defaults feature gate restores the previous defaults — a single switch, not a per-release dance.
The biggest quality-of-life feature for Helm-managed CRDs: Flux 2.8 supports CEL-based health check expressions on HelmReleases, giving you the same flexibility already available in the Kustomization API.
apiVersion: helm.toolkit.fluxcd.io/v1
kind: HelmRelease
metadata:
name: keycloak
namespace: auth
spec:
interval: 5m
chart:
spec:
chart: keycloak
version: "26.x"
sourceRef:
kind: HelmRepository
name: codecentric
healthChecks:
- apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
name: keycloak
namespace: auth
timeout: 5m
expression: |
status.conditions.filter(c, c.type == 'Ready' && c.status == 'True').size() > 0
The expression evaluates against the object's status. The release only becomes ready when the custom resource reports Ready=True — something Helm's legacy readiness logic could never understand.
.status.inventory — ObservabilityHelmReleases now track the inventory of managed resources in .status.inventory, giving operators full visibility for debugging and auditing. Combined with the CEL health checks, you can answer "what does this release actually manage, and is it healthy?" from the API alone — no digging into secrets or release history.
Two smaller features round out the release for pipeline-minded teams:
Flux can also comment on Pull Requests directly from notifications now, and GitHub App installation IDs are auto-detected from the repository owner — small ergonomics wins that remove API tokens from your notification setup.
CancelHealthCheckOnNewRevisionFlux 2.8 introduces the CancelHealthCheckOnNewRevision feature gate for both Kustomizations and HelmReleases. When a new revision arrives mid-health-check, Flux cancels the stale check instead of letting it run to completion. On a failed rollout followed by a fix commit, the fix no longer waits behind the old revision's timeout — recovery time drops dramatically.
Flux 2.8 adds Cosign v3 support for verifying OCI artifacts and container images on OCIRepositories. Note the version pin: Flux pins cosign to v2.6.1, so verify your signing tooling produces signatures that v2.6.1 can validate.
helm template --validate on every chart you manage. Most charts work unchanged; the ones that break are usually post-renderer or hook related.separate (or nohooks for exact Helm 3 behavior) rather than fighting the combined default.flux upgrade --install — the deprecated APIs from 2024 reach end-of-life in v2.8 and are removed from the CRDs, so follow the official upgrade procedure for v2.7+.UseHelm3Defaults only if you must. The gate exists, but the defaults (SSA + kstatus) are better — test on a staging cluster before opting out.nohooks — it matches Helm 3 exactlyUseHelm3Defaults on the affected controllerskstatus flips existing releases. The health-check switch applies to all HelmReleases on upgrade, not just new ones. If a release depended on Helm's legacy readiness behavior — e.g. a Job that reports success via an annotation rather than standard status conditions — it may now show Progressing forever. Grep your workloads for non-standard status patterns before upgrading, and add CEL health checks for those releases in the same change.
Hooks + Kustomize is the most common breakage. The combined post-render strategy surfaces exactly one class of error: "multiple objects with the same fully-qualified name." If your post-render logs show that after the upgrade, the fix is separate, not fighting the hook stream.
Verify before you trust. Flux's Cosign pin (v2.6.1) means signatures produced by newer cosign clients may not verify. Re-sign with a compatible version in your release pipeline before switching OCIRepository verification on.