From 6a4b24bc2e7ee0f5a770f9758cf52a7f9454d524 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Tue, 7 Oct 2025 00:16:04 +0300 Subject: [PATCH] Add upgrade procedure to Flux Operator docs Signed-off-by: Stefan Prodan --- docs/distribution/install.md | 2 +- docs/distribution/upgrade.md | 128 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 docs/distribution/upgrade.md diff --git a/docs/distribution/install.md b/docs/distribution/install.md index 0cedf057..6bc430a7 100644 --- a/docs/distribution/install.md +++ b/docs/distribution/install.md @@ -1,6 +1,6 @@ --- title: Flux Distribution Installation -description: FluxCD Enterprise installation and upgrade guide +description: FluxCD Enterprise installation guide --- # Flux Distribution Installation diff --git a/docs/distribution/upgrade.md b/docs/distribution/upgrade.md new file mode 100644 index 00000000..c5f35135 --- /dev/null +++ b/docs/distribution/upgrade.md @@ -0,0 +1,128 @@ +--- +title: Flux Distribution Upgrade +description: FluxCD Enterprise upgrade procedure +--- + +# Flux Distribution Upgrade Procedure + +The Flux distribution has a release cadence of approximately one minor release every three months, +with patch releases in between. On production clusters, it is recommended to configure Flux Operator +to automatically upgrade Flux to the latest patch release in the specified minor version range. + +!!! tip "Flux Operator" + + The [Flux Operator](../operator/index.md) APIs are stable and backward compatible, + so it is safe to upgrade the operator to the latest version at any time. + +## Upgrading the Flux Operator + +Depending on the installation [method](../operator/install.md), +upgrading the Flux Operator should be done in an automated manner. + +If you installed the operator with the Helm CLI, you can configure automated +upgrades with a Flux `HelmRelease` as follows: + +```yaml +apiVersion: fluxcd.controlplane.io/v1 +kind: ResourceSet +metadata: + name: flux-operator + namespace: flux-system +spec: + inputs: + - interval: "1h" # check for updates every hour + version: "*" # upgrade to latest stable version + resources: + - apiVersion: source.toolkit.fluxcd.io/v1 + kind: OCIRepository + metadata: + name: << inputs.provider.name >> + namespace: << inputs.provider.namespace >> + spec: + interval: << inputs.interval | quote >> + url: oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator + layerSelector: + mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip" + operation: copy + ref: + semver: << inputs.version | quote >> + - apiVersion: helm.toolkit.fluxcd.io/v2 + kind: HelmRelease + metadata: + name: << inputs.provider.name >> + namespace: << inputs.provider.namespace >> + spec: + interval: 12h + releaseName: << inputs.provider.name >> + serviceAccountName: << inputs.provider.name >> + chartRef: + kind: OCIRepository + name: << inputs.provider.name >> + values: + reporting: + interval: 30s +``` + +If you installed the operator with [Terraform/OpenTofu](https://github.com/controlplaneio-fluxcd/flux-operator/tree/main/config/terraform), +update the `version` argument in the `helm_release` resource and apply the changes with `terraform apply`. + +If you installed the operator from [OperatorHub](https://operatorhub.io/operator/flux-operator), +you can configure automatic upgrades by setting `Approval` to `Automatic` in OpenShift. + +## Upgrading the Flux Distribution + +It is recommended to set the Flux distribution version in the `FluxInstance` manifest +to a specific minor version, such as `2.6.x`, to have more control over the upgrade process. + +### Migrate to Flux stable APIs in Git + +!!! warning "Flux beta APIs EOL" + + In Flux v2.7, the deprecated **beta1** APIs have reached their end of life and are no longer supported. + + In Flux v2.8, the deprecated **beta2** APIs will reach their end of life on Q1 2026. + +Before upgrading to Flux v2.7 or later, make sure to migrate all your manifests +to the Flux v2.6 stable APIs in your Git repositories by using the `flux migrate -f` command: + +```sh +git clone +cd +flux migrate -v 2.6 -f . +git commit -am "Migrate to Flux v2.6 stable APIs" +git push +``` + +### Update the Flux Instance + +After migrating your resources in all Git repositories, +update the `FluxInstance` manifest to the desired version: + +```yaml +apiVersion: fluxcd.controlplane.io/v1 +kind: FluxInstance +metadata: + name: flux + namespace: flux-system +spec: + distribution: + version: "2.7.x" +``` + +The operator will automatically upgrade the Flux components and +migrate the Flux APIs to their latest API versions in-cluster. + +### Kubernetes Version Compatibility + +When planning an upgrade of the Flux distribution, make sure to check the compatibility +with your Kubernetes cluster version. + +The Enterprise distribution of Flux supports the **6 most recent minor versions** of Kubernetes, +including Long-Term Support (LTS) versions offered by cloud providers, +and the 3 most recent OpenShift versions. +The list of supported Kubernetes and OpenShift versions is updated with every Flux Enterprise minor +release and can be found in the [release notes](https://github.com/controlplaneio-fluxcd/distribution/releases). + +The CNCF Flux distribution supports the **3 most recent minor versions** of Kubernetes. +The list of supported versions is updated with every Flux minor release +and can be found in the [flux2 release notes](https://github.com/fluxcd/flux2/releases). diff --git a/mkdocs.yml b/mkdocs.yml index 99fa0693..8a5175d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,6 +87,7 @@ nav: - Flux Distribution: - Introduction: distribution/index.md - Installation: distribution/install.md + - Upgrade: distribution/upgrade.md - Security: distribution/security.md - Guides: - Flux Architecture Overview: guides/flux-architecture.md