From 23fa9d8876dbc4508b96ca10f848b58392af1ba5 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Tue, 11 Jun 2024 21:04:32 +0300 Subject: [PATCH] Add Flux configuration guide Signed-off-by: Stefan Prodan --- docs/operator/flux-config.md | 124 +++++++++++++++++++++++++++++++++++ docs/operator/index.md | 18 ++--- docs/operator/install.md | 66 +++++++------------ mkdocs.yml | 3 +- 4 files changed, 159 insertions(+), 52 deletions(-) create mode 100644 docs/operator/flux-config.md diff --git a/docs/operator/flux-config.md b/docs/operator/flux-config.md new file mode 100644 index 0000000..8b78c1d --- /dev/null +++ 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 index 6e7072c..b1c5116 100644 --- 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 index 14b1cd1..17c42b1 100644 --- 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 index 30cb18e..83730a6 100644 --- 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