From 32405177db8becd6ed596842e9aa44bdaa4a4b88 Mon Sep 17 00:00:00 2001
From: Stefan Prodan <stefan.prodan@gmail.com>
Date: Tue, 11 Jun 2024 23:08:27 +0300
Subject: [PATCH] Add boostrap migration guide

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
---
 docs/operator/flux-bootstrap-migration.md | 90 +++++++++++++++++++++++
 docs/operator/flux-sync.md                |  2 +-
 mkdocs.yml                                |  3 +-
 3 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 docs/operator/flux-bootstrap-migration.md

diff --git a/docs/operator/flux-bootstrap-migration.md b/docs/operator/flux-bootstrap-migration.md
new file mode 100644
index 0000000..c511394
--- /dev/null
+++ b/docs/operator/flux-bootstrap-migration.md
@@ -0,0 +1,90 @@
+# Flux Bootstrap Migration
+
+Assuming you have a cluster bootstrapped with the Flux CLI or the Terraform Provider,
+you can migrate to an operator-managed Flux with zero downtime.
+
+## Install the Flux Operator
+
+Install the Flux Operator in the same namespace where Flux is deployed, for example using Helm:
+
+```shell
+helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
+  --namespace flux-system
+```
+
+Or by using an alternative installation method described in the [installation guide](install.md).
+
+## Create a Flux Instance
+
+Create a `FluxInstance` resource named **flux** in the `flux-system` namespace using
+the same configuration as for `flux bootstrap`. 
+
+For example, if you have bootstrapped the cluster with the following command:
+
+```shell
+flux bootstrap github \
+  --owner=my-org \
+  --repository=my-fleet \
+  --branch=main \
+  --path=clusters/my-cluster
+```
+
+The equivalent `FluxInstance` configuration would look like this:
+
+```yaml
+apiVersion: fluxcd.controlplane.io/v1
+kind: FluxInstance
+metadata:
+  name: flux
+  namespace: flux-system
+spec:
+  distribution:
+    version: "2.x"
+    registry: "ghcr.io/fluxcd"
+  components:
+    - source-controller
+    - kustomize-controller
+    - helm-controller
+    - notification-controller
+  cluster:
+    type: kubernetes
+    multitenant: false
+    networkPolicy: true
+    domain: "cluster.local"
+  sync:
+    kind: GitRepository
+    url: "ssh://git@github.com/my-org/my-fleet.git"
+    ref: "refs/heads/main"
+    path: "clusters/my-cluster"
+    pullSecret: "flux-system"
+```
+
+Apply the `FluxInstance` resource to the cluster:
+
+```shell
+kubectl apply -f flux-instance.yaml
+```
+
+Once the resource is reconciled, the operator will take over the management of the Flux components,
+the Flux GitRepository and Kustomization.
+
+To verify that the migration was successful, check the status of the `FluxInstance`:
+
+```shell
+kubectl -n flux-system get fluxinstance flux
+```
+
+Running the trace command should result in a "Not managed by Flux" message:
+
+```shell
+flux trace kustomization flux-system
+```
+
+## Cleanup the repository
+
+To finalize the migration, remove the Flux manifests from the Git repository:
+
+1. Checkout the main branch of the Flux repository that was used to bootstrap the cluster.
+2. Delete the `flux-system` directory from the repository `clusters/my-cluster` directory.
+3. Optionally, place the `FluxInstance` YAML manifest in the `clusters/my-cluster` directory.
+4. Commit and push the changes to the Flux repository.
diff --git a/docs/operator/flux-sync.md b/docs/operator/flux-sync.md
index 2d73a14..d809120 100644
--- a/docs/operator/flux-sync.md
+++ b/docs/operator/flux-sync.md
@@ -1,4 +1,4 @@
-# Flux Sync Configuration
+# Flux Cluster Sync Configuration
 
 The `FluxInstance` resource can be configured to instruct the operator to generate
 a Flux source (`GitRepository`, `OCIRepository` or `Bucket`) and a Flux `Kustomization`
diff --git a/mkdocs.yml b/mkdocs.yml
index 32bc1e6..b8f4d4f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -93,7 +93,8 @@ nav:
       - Installation: operator/install.md
       - Configuration:
           - Flux Controllers: operator/flux-config.md
-          - Flux Sync: operator/flux-sync.md
+          - Flux Cluster Sync: operator/flux-sync.md
+          - Flux Bootstrap Migration: operator/flux-bootstrap-migration.md
       - API Reference:
           - FluxInstance CRD: operator/fluxinstance.md
   - Pricing: pricing/index.md