Merge pull request #2519 from fluxcd/fo-upgrade

Add operator upgrade procedure

Author: stefanprodan

content/en/flux/concepts.md

@@ -9,9 +9,9 @@ These are some core concepts in Flux.
 ## GitOps
 
 GitOps is a way of managing your infrastructure and applications so that whole system
-is described declaratively and version controlled (most likely in a Git repository),
-and having an automated process that ensures that the deployed environment
-matches the state specified in a repository.
+is described declaratively and version controlled, and having an automated process
+that ensures that the deployed environment matches the state specified
+in one or more Git repositories.
 
 For more information, take a look at the following resources:
 
@@ -36,6 +36,7 @@ For more information, take a look at the following resources:
 
 * [Flux OCI Artifacts documentation](/flux/cheatsheets/oci-artifacts/)
 * [OCI Bootstrap with Flux Operator](/flux/installation/#bootstrap-with-flux-operator)
+* [Gitless GitOps overview](https://fluxoperator.dev/gitless-gitops/)
 
 ## GitOps Toolkit (gotk)
 

content/en/flux/installation/_index.md

@@ -189,11 +189,11 @@ helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-opera
 ```
 
 The Flux Operator can be installed using Helm, Terraform, OpenTofu, OperatorHub, and other methods.
-For more information, refer to the [installation guide](https://fluxcd.control-plane.io/operator/install/).
+For more information, refer to the [installation guide](https://fluxoperator.dev/docs/guides/install/).
 
 #### Configure the Flux Instance
 
-Create a [FluxInstance](https://fluxcd.control-plane.io/operator/fluxinstance/) resource
+Create a [FluxInstance](https://fluxoperator.dev/docs/crd/fluxinstance/) resource
 named `flux` in the `flux-system` namespace to install the latest Flux stable version and configure the
 Flux controllers to sync the cluster state from an OCI artifact stored in GitHub Container Registry:
 
@@ -205,14 +205,15 @@ metadata:
   namespace: flux-system
   annotations:
     fluxcd.controlplane.io/reconcileEvery: "1h"
-    fluxcd.controlplane.io/reconcileTimeout: "5m"
+    fluxcd.controlplane.io/reconcileTimeout: "10m"
 spec:
   distribution:
     version: "2.x"
     registry: "ghcr.io/fluxcd"
     artifact: "oci://ghcr.io/controlplaneio-fluxcd/flux-operator-manifests"
   components:
     - source-controller
+    - source-watcher
     - kustomize-controller
     - helm-controller
     - notification-controller
@@ -248,14 +249,14 @@ spec:
 
 > For more information on how to configure syncing from Git repositories,
 > container registries, and S3-compatible storage, refer to the
-> [cluster sync guide](https://fluxcd.control-plane.io/operator/flux-sync/).
+> [cluster sync guide](https://fluxoperator.dev/docs/instance/sync/).
 
 The operator can automatically upgrade the Flux controllers and their CRDs when a new version is available.
 To restrict the upgrade to patch versions only, set the `distribution.version` field to e.g. `2.7.x`
 or to a fixed version e.g. `2.7.0` to disable automatic upgrades.
 
 The Flux Operator can take over the management of existing installations from the Flux CLI or other tools.
-For a step-by-step guide, refer to the [Flux Operator migration guide](https://fluxcd.control-plane.io/operator/).
+For a step-by-step guide, refer to the [Flux Operator migration guide](https://fluxoperator.dev/docs/guides/migration/).
 
 ### Dev install
 

content/en/flux/installation/upgrade.md

@@ -100,6 +100,74 @@ and run `terraform apply`.
 
 The upgrade performed with Terraform behaves in the same way as the [upgrade with Flux CLI](#upgrade-with-flux-cli).
 
+### Upgrade with Flux Operator
+
+If you've used the [Flux Operator](https://fluxoperator.dev/) to deploy Flux,
+first update the operator to the latest version, then update the `FluxInstance` resource
+to specify the latest Flux minor version.
+
+The Flux Operator can be automatically updated by creating a [ResourceSet](https://fluxoperator.dev/docs/crd/resourceset/)
+that references the latest version of the operator's [Helm chart](https://fluxoperator.dev/docs/charts/flux-operator/):
+
+```yaml
+apiVersion: fluxcd.controlplane.io/v1
+kind: ResourceSet
+metadata:
+  name: flux-operator
+  namespace: flux-system
+spec:
+  inputs:
+    - version: "*"
+      interval: 12h
+  resources:
+   - apiVersion: source.toolkit.fluxcd.io/v1
+     kind: OCIRepository
+     metadata:
+      name: << inputs.provider.name >>
+      namespace: << inputs.provider.namespace >>
+     spec:
+      interval: << inputs.provider.interval >>
+      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: 1h
+      releaseName: << inputs.provider.name >>
+      serviceAccountName: << inputs.provider.name >>
+      upgrade:
+        strategy:
+          name: RetryOnFailure
+      chartRef:
+        kind: OCIRepository
+        name: << inputs.provider.name >>
+```
+
+After the operator is up-to-date, if there is a new Flux minor version available,
+update the `FluxInstance` resource to specify the latest version:
+
+```yaml
+apiVersion: fluxcd.controlplane.io/v1
+kind: FluxInstance
+metadata:
+  name: flux
+  namespace: flux-system
+spec:
+  distribution:
+    version: "2.8.x" # update to the latest minor version
+```
+
+Note that both the `ResourceSet` and the `FluxInstance` resources should
+be placed in the `clusters/<cluster>/flux-system` directory of the Git repository
+used to bootstrap Flux with the operator.
+
 ### Upgrade with kubectl
 
 If you've installed Flux directly on the cluster with kubectl,