Add Flux configuration guide

Signed-off-by: Stefan Prodan <[email protected]>
controlplaneio-fluxcd · Jun 11, 2024 · 23fa9d8 · 23fa9d8
1 parent b57d29d
commit 23fa9d8
Show file tree

Hide file tree

Showing 4 changed files with 159 additions and 52 deletions.
diff --git a/docs/operator/flux-config.md b/docs/operator/flux-config.md
@@ -0,0 +1,124 @@
+# Flux configuration
+
+The Flux Operator comes with a Kubernetes CRD called [FluxInstance](fluxinstance.md).
+A single custom resource of this kind can exist in a Kubernetes cluster with the name
+**flux** that must be created in the same namespace where the operator is deployed.
+
+The `FluxInstance` resource is used to install and configure the automated update
+of the Flux distribution.
+
+## Default configuration
+
+Example of a minimal `FluxInstance` resource:
+
+```yaml
+apiVersion: fluxcd.controlplane.io/v1
+kind: FluxInstance
+metadata:
+  name: flux
+  namespace: flux-system
+spec:
+  distribution:
+    version: "2.3.x"
+    registry: "ghcr.io/fluxcd"
+  cluster:
+    type: kubernetes
+```
+
+!!! tip "Enterprise Distribution"
+
+    To install the enterprise distribution of Flux, point the operator to the ControlPlane registry:
+    
+    ```yaml
+    apiVersion: fluxcd.controlplane.io/v1
+    kind: FluxInstance
+    metadata:
+      name: flux
+      namespace: flux-system
+    spec:
+      distribution:
+        version: "2.3.x"
+        registry: "ghcr.io/controlplaneio-fluxcd/distroless"
+        imagePullSecret: "flux-enterprise-auth"
+    ```
+
+    The operator will check for updates in the ControlPlane
+    [distribution repository](https://github.com/controlplaneio-fluxcd/distribution).
+    If a new patch version is available, the operator will update the Flux components by pinning the
+    container images to the latest digest published in the ControlPlane registry.
+
+Save the above manifest to a file and apply it with `kubectl`:
+
+```shell
+kubectl apply -f flux-instance.yaml
+```
+
+The operator will reconcile the `FluxInstance` resource and install
+the latest upstream Flux version in the `2.3` range with the specified components.
+Every hour, the operator will check for Flux patch releases and apply them if available.
+
+To verify the installation status:
+
+```shell
+kubectl -n flux-system get fluxinstance flux
+```
+
+To uninstall the Flux instance:
+
+```shell
+kubectl -n flux-system delete fluxinstance flux
+```
+
+## Custom configuration
+
+The Flux distribution can be customized by specifying the components to install,
+the cluster type, multitenancy, network policy, storage class and size, and kustomize patches.
+
+For example, to install the latest Flux version with the multi-tenancy lockdown enabled
+and persistent storage for the source-controller:
+
+```yaml
+apiVersion: fluxcd.controlplane.io/v1
+kind: FluxInstance
+metadata:
+  name: flux
+  namespace: flux-system
+  annotations:
+    fluxcd.controlplane.io/reconcileEvery: "1h"
+    fluxcd.controlplane.io/reconcileTimeout: "5m"
+spec:
+  distribution:
+    version: "2.x"
+    registry: "ghcr.io/fluxcd"
+  components:
+    - source-controller
+    - kustomize-controller
+    - helm-controller
+    - notification-controller
+    - image-reflector-controller
+    - image-automation-controller
+  cluster:
+    type: kubernetes
+    multitenant: true
+    networkPolicy: true
+    domain: "cluster.local"
+  storage:
+    class: "standard"
+    size: "10Gi"
+  kustomize:
+    patches:
+      - target:
+          kind: Deployment
+          name: "(kustomize-controller|helm-controller)"
+        patch: |
+          - op: add
+            path: /spec/template/spec/containers/0/args/-
+            value: --concurrent=10
+          - op: add
+            path: /spec/template/spec/containers/0/args/-
+            value: --requeue-dependency=5s
+```
+
+To find out more about the available configuration options, refer to the
+[FluxInstance API reference](fluxinstance.md).
+```
diff --git a/docs/operator/index.md b/docs/operator/index.md
@@ -1,18 +1,18 @@
 # Flux Operator Introduction
 
 The Flux Operator is a Kubernetes CRD controller that manages
-the lifecycle of the ControlPlane enterprise distribution for Flux CD.
+the lifecycle of CNCF Flux and the ControlPlane enterprise distribution.
 
 ## Features
 
-- Provide a declarative API for the installation and upgrade of the Flux distribution.
-- Automate patching for hotfixes and CVEs affecting the Flux controllers container images.
-- Provide first-class support for OpenShift, Azure, AWS, GCP and other marketplaces.
-- Simplify the configuration of multi-tenancy lockdown on shared Kubernetes clusters.
-- Provide a security-first approach to the Flux deployment and FIPS compliance.
-- Incorporate best practices for running Flux at scale with persistent storage, sharding and horizontal scaling.
-- Manage the update of Flux custom resources and prevent disruption during the upgrade process.
-- Facilitate a clean uninstall and reinstall process without affecting the Flux-managed workloads.
+- Provides a declarative API for the installation, configuration and upgrade of Flux.
+- Automates the patching of hotfixes and CVEs affecting the Flux controllers container images.
+- Simplifies the configuration of multi-tenancy lockdown on shared Kubernetes clusters.
+- Provides a security-first approach to the Flux deployment and FIPS compliance.
+- Incorporates best practices for running Flux at scale with persistent storage and vertical scaling.
+- Manages the update of Flux custom resources and prevents disruption during the upgrade process.
+- Facilitates a clean uninstall and reinstall process without affecting the Flux-managed workloads.
+- Provides first-class support for OpenShift, Azure, AWS, GCP and other marketplaces.
 
 ## License
 

diff --git a/docs/operator/install.md b/docs/operator/install.md
@@ -6,7 +6,7 @@ statically compiled as a single binary with no external dependencies.
 
 ## Install methods
 
-The Flux Operator can be installed with Helm, Operator Lifecycle Manager, or kubectl.
+The Flux Operator can be installed with Helm, Terraform, Operator Lifecycle Manager, or kubectl.
 It is recommended to install the operator in a dedicated namespace, such as `flux-system`.
 
 ### Helm
@@ -21,6 +21,21 @@ helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-opera
   --create-namespace
 ```
 
+### Terraform
+
+Installing the Flux Operator with Terraform is possible using the
+[Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs):
+
+```hcl
+resource "helm_release" "flux_operator" {
+  name       = "flux-operator"
+  namespace  = "flux-system"
+  repository = "oci://ghcr.io/controlplaneio-fluxcd/charts"
+  chart      = "flux-operator"
+  create_namespace = true
+}
+```
+
 ### Operator Lifecycle Manager (OLM)
 
 The Flux Operator can be installed on OpenShift using the bundle published on OperatorHub
@@ -50,57 +65,24 @@ applying the Kubernetes manifests published on the releases page:
 kubectl apply -f https://github.com/controlplaneio-fluxcd/flux-operator/releases/latest/download/install.yaml
 ```
 
-## Flux configuration
-
-The Flux Operator comes with a Kubernetes CRD called [FluxInstance](fluxinstance.md).
-A single custom resource of this kind can exist in a Kubernetes cluster with the name
-**flux** that must be created in the same namespace where the operator is deployed.
-
-The `FluxInstance` resource is used to install and configure the automated update
-of the Flux distribution.
-
-Example of a minimal `FluxInstance` resource:
-
-```yaml
-apiVersion: fluxcd.controlplane.io/v1
-kind: FluxInstance
-metadata:
-  name: flux
-  namespace: flux-system
-  annotations:
-    fluxcd.controlplane.io/reconcileEvery: "1h"
-    fluxcd.controlplane.io/reconcileTimeout: "5m"
-spec:
-  distribution:
-    version: "2.3.x"
-    registry: "ghcr.io/fluxcd"
-  components:
-    - source-controller
-    - kustomize-controller
-    - helm-controller
-    - notification-controller
-  cluster:
-    type: kubernetes
-```
+## Uninstall
 
-Save the above manifest to a file and apply it with `kubectl`:
+Before uninstalling the Flux Operator, make sure to delete the `FluxInstance` resources with:
 
 ```shell
-kubectl apply -f flux-instance.yaml
+kubectl -n flux-system delete fluxinstances --all
 ```
 
-The operator will reconcile the `FluxInstance` resource and install
-the latest upstream Flux version in the `2.3` range with the specified components.
-Every hour, the operator will check for Flux patch releases and apply them if available.
+The operator will uninstall Flux from the cluster without affecting the Flux-managed workloads.
 
-To verify the installation status:
+Verify that the Flux controllers have been removed:
 
 ```shell
-kubectl -n flux-system get fluxinstance flux
+kubectl -n flux-system get deployments
 ```
 
-To uninstall the Flux instance:
+Uninstall the Flux Operator with your preferred method, e.g. Helm:
 
 ```shell
-kubectl -n flux-system delete fluxinstance flux
+helm -n flux-system uninstall flux-operator
 ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -91,7 +91,8 @@ nav:
   - Flux Operator:
       - Introduction: operator/index.md
       - Installation: operator/install.md
+      - Flux Configuration: operator/flux-config.md
       - API Reference:
-          - FluxInstance: operator/fluxinstance.md
+          - FluxInstance CRD: operator/fluxinstance.md
   - Pricing: pricing/index.md
   - Contact: https://control-plane.io/contact/?inquiry=fluxcd