The Flux v2 migration was "nearly done" two years ago. A handful of legacy v1 HelmReleases still run production, a few v2 files in git were never switched on, and half the repo still uses API versions the next Flux release will stop serving. The assistant works through all of it as small, reviewable MRs, in an order that never leaves a release without an owner.
helm.fluxcd.io/v1 HelmReleases, stale v2 files, Flux manifests on deprecated API versions, the installed Flux version.
Every HelmRelease on the old helm.fluxcd.io/v1 API is
listed from the live cluster, then matched to its file in git. A v1
release with no Ready v2 counterpart is a migration candidate.
Here: payments/invoice-renderer, still reconciled by
the Flux v1 Helm operator.
The v1 spec is restructured into the v2 shape:
chart.spec.chart, chart.spec.version, a
sourceRef. The values block is carried over
verbatim. A migration is not the moment to change behaviour.
When the model's diff is unusable, a deterministic template built from the v1 release produces the same result without it.
v1 embedded the chart repository URL in each release. v2 needs a HelmRepository object. One is added only when that URL is not already declared in the repo, so ten releases from one repository share one source.
New files are wired into the directory's
kustomization.yaml, or left to a Flux Kustomization that
already walks the directory.
The v2 HelmRelease is only activated when the v1 release is proven inactive, or proven equivalent and suspended in the same change. Anything the assistant cannot prove leaves the proposal held for review with the evidence, not shipped.
A new release landing under a Kustomization with
wait: true gets a banner and high risk: one stuck
release there stalls every sibling.
Sometimes a v2 file exists in git but was never wired in, while the live v1 release kept being upgraded by hand. Copying git over the cluster would be a downgrade.
The running pod's image tag is compared with the chart's appVersion table to decide the direction. The result is a values-merge MR held for your confirmation, never shipped on its own.
Once the v2 HelmRelease for the same release is Ready in the cluster, the old v1 object is strictly redundant. A separate, low-risk MR removes it.
Two MRs, two risks: the migration can be reverted without resurrecting anything, and the deletion never races the cut-over.
The cluster reports which versions of each Flux CRD it serves. Every
manifest still on an older served version gets a one-line
apiVersion bump, with comments and key order untouched.
All of them ride one MR per cluster.
When a version is on Flux's published removal schedule, the MR says which Flux release will stop serving it.
The Flux version in gotk-components.yaml is compared
with the current flux CLI. When it is behind, the
install manifest is regenerated with the same components and
proposed as an MR.
If deprecated API versions are still in the repo, the upgrade MR lists them as prerequisites and carries high risk until the bundled bump MR is merged.
apiVersion: helm.fluxcd.io/v1 kind: HelmRelease metadata: name: invoice-renderer namespace: payments spec: releaseName: invoice-renderer chart: repository: https://charts.example.com/ name: invoice-renderer version: 3.2.0 values: replicaCount: 2 pdf: { fonts: [ noto, dejavu ], timeoutSeconds: 45 }
apiVersion: helm.toolkit.fluxcd.io/v2 kind: HelmRelease metadata: { name: invoice-renderer, namespace: payments } spec: interval: 10m chart: spec: chart: invoice-renderer version: 3.2.0 sourceRef: { kind: HelmRepository, name: example-charts } values: # verbatim from v1 replicaCount: 2 pdf: { fonts: [ noto, dejavu ], timeoutSeconds: 45 }
- releases/payments/invoice-renderer.yaml (deleted) releases/kustomization.yaml - - payments/invoice-renderer.yaml
apps/payments/helmrelease_invoice-renderer.yaml -apiVersion: helm.toolkit.fluxcd.io/v2beta1 +apiVersion: helm.toolkit.fluxcd.io/v2 infrastructure/sources/helmrepository_example-charts.yaml -apiVersion: source.toolkit.fluxcd.io/v1beta2 +apiVersion: source.toolkit.fluxcd.io/v1 clusters/prod/apps.yaml -apiVersion: kustomize.toolkit.fluxcd.io/v1beta2 +apiVersion: kustomize.toolkit.fluxcd.io/v1 … 60 more files, one line each
# Flux Version: v2.6.4 (clusters/prod/flux-system/gotk-components.yaml) $ flux --version flux version 2.7.2 $ flux install --components=… --components-extra=… --export ✓ regenerated with the same components ! 4 files still on deprecated apiVersions → listed as prerequisites
Illustrative, shaped like the real migration MR: same title format, same labels, same cut-over rule.
gitops-ai/migrate-payments-invoice-renderer into main · 4 files · +27 −1Migrates payments/invoice-renderer from the legacy Flux v1 Helm operator to a Flux v2 HelmRelease. Chart invoice-renderer 3.2.0 stays on the same version; values are carried over verbatim.
apps/payments/helmrelease_invoice-renderer.yaml.example-charts for https://charts.example.com/, not declared in this repo before.spec.suspend: true on the v1 HelmRelease, so only one controller acts on the release.apps/payments/kustomization.yaml.It does not delete the v1 object. That comes as a separate MR once the v2 HelmRelease reports Ready.
| Check | Result |
|---|---|
| Chart name and version | v1 and v2 identical (3.2.0). |
| Values | Identical, byte for byte. |
| v1 state | Equivalent; suspended in this change. |
| Covering Kustomization | apps, sources this repository, wait: false. |
| Disposition | Safe to activate. |
flux get hr -n payments invoice-renderer: Ready, chart 3.2.0.Revert this MR: the v1 release is un-suspended and resumes ownership.
+ apps/payments/helmrelease_invoice-renderer.yaml (new, 19 lines) + infrastructure/sources/helmrepository_example-charts.yaml (new) apps/payments/kustomization.yaml + - helmrelease_invoice-renderer.yaml releases/payments/invoice-renderer.yaml spec: + suspend: true releaseName: invoice-renderer
Values block diffed against v1: identical. HelmRepository URL matches the v1 chart repository. Suspend and activation are in the same change. LGTM.
A migration is only finished when every release has exactly one owner and every file is applied.
gotk-components.yaml contains a controller it does not recognise, no self-upgrade is proposed rather than clobbering your customisation.flux install cannot set them)