From c418a719b59874972ab23bcc26b0ed2fb4ec004a Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Fri, 21 Jun 2024 01:02:23 +0300 Subject: [PATCH] Add `FluxReport` API docs Signed-off-by: Stefan Prodan --- README.md | 17 ++- docs/api/v1/fluxreport.md | 252 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 268 insertions(+), 1 deletion(-) create mode 100644 docs/api/v1/fluxreport.md diff --git a/README.md b/README.md index 0de02b5..ede3ff1 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ the lifecycle of CNCF [Flux CD](https://fluxcd.io) and the - Automates the patching of hotfixes and CVEs affecting the Flux controllers container images. - Simplifies the configuration of multi-tenancy lockdown on shared Kubernetes clusters. - Allows syncing the cluster state from Git repositories, OCI artifacts and S3-compatible storage. +- Generates detailed reports about the Flux deployment readiness status and reconcilers statistics. - 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. @@ -55,7 +56,7 @@ helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-opera ### Install the Flux Controllers Create a [FluxInstance](https://fluxcd.control-plane.io/operator/fluxinstance/) resource -in the `flux-system` namespace to install the latest Flux stable version: +named `flux` in the `flux-system` namespace to install the latest Flux stable version: ```yaml apiVersion: fluxcd.controlplane.io/v1 @@ -136,6 +137,20 @@ flux create secret git flux-system \ > container registries and S3-compatible storage, refer to the > [cluster sync guide](https://fluxcd.control-plane.io/operator/flux-sync/). +### Monitor the Flux Installation + +To monitor the Flux deployment status, check the +[FluxReport](https://fluxcd.control-plane.io/operator/fluxreport/) +resource in the `flux-system` namespace: + +```shell +kubectl get fluxreport/flux -n flux-system -o yaml +``` + +The report is update at regular intervals and contains information about the deployment +readiness status, the distribution details, reconcilers statistics, Flux CRDs versions, +the cluster sync status and more. + ## License The Flux Operator is an open-source project licensed under the diff --git a/docs/api/v1/fluxreport.md b/docs/api/v1/fluxreport.md new file mode 100644 index 0000000..daf1d6a --- /dev/null +++ b/docs/api/v1/fluxreport.md @@ -0,0 +1,252 @@ +# Flux Report CRD + +**FluxReport** is an API that reflects the observed state of a Flux installation. +Its purpose is to aid in monitoring and troubleshooting Flux by providing +information about the installed components and their readiness, the distribution details, +reconcilers statistics, cluster sync status, etc. + +A single custom resource of this kind can exist in a Kubernetes cluster +with the name `flux`. The resource is automatically generated in the same namespace +where the flux-operator is deployed and is updated by the operator at regular intervals. + +## Example + +The following example shows a FluxReport custom resource generated on a cluster +where a [FluxInstance](fluxinstance.md) was deployed: + +```yaml +apiVersion: fluxcd.controlplane.io/v1 +kind: FluxReport +metadata: + name: flux + namespace: flux-system +spec: + components: + - image: ghcr.io/fluxcd/helm-controller:v1.0.1@sha256:a67a037faa850220ff94d8090253732079589ad9ff10b6ddf294f3b7cd0f3424 + name: helm-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' + - image: ghcr.io/fluxcd/kustomize-controller:v1.3.0@sha256:48a032574dd45c39750ba0f1488e6f1ae36756a38f40976a6b7a588d83acefc1 + name: kustomize-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' + - image: ghcr.io/fluxcd/notification-controller:v1.3.0@sha256:c0fab940c7e578ea519097d36c040238b0cc039ce366fdb753947428bbf0c3d6 + name: notification-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' + - image: ghcr.io/fluxcd/source-controller:v1.3.0@sha256:161da425b16b64dda4b3cec2ba0f8d7442973aba29bb446db3b340626181a0bc + name: source-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' + distribution: + entitlement: Issued by controlplane + managedBy: flux-operator + status: Installed + version: v2.3.0 + reconcilers: + - apiVersion: helm.toolkit.fluxcd.io/v2 + kind: HelmRelease + stats: + failing: 1 + running: 42 + suspended: 3 + - apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + stats: + failing: 0 + running: 5 + suspended: 0 + - apiVersion: notification.toolkit.fluxcd.io/v1 + kind: Receiver + stats: + failing: 0 + running: 1 + suspended: 0 + - apiVersion: notification.toolkit.fluxcd.io/v1beta3 + kind: Alert + stats: + failing: 0 + running: 1 + suspended: 0 + - apiVersion: notification.toolkit.fluxcd.io/v1beta3 + kind: Provider + stats: + failing: 0 + running: 1 + suspended: 0 + - apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + stats: + failing: 0 + running: 2 + suspended: 0 + totalSize: 3.7 MiB + - apiVersion: source.toolkit.fluxcd.io/v1 + kind: HelmChart + stats: + failing: 1 + running: 55 + suspended: 0 + totalSize: 15.7 MiB + - apiVersion: source.toolkit.fluxcd.io/v1 + kind: HelmRepository + stats: + failing: 0 + running: 7 + suspended: 3 + totalSize: 40.5 MiB + - apiVersion: source.toolkit.fluxcd.io/v1beta2 + kind: Bucket + stats: + failing: 0 + running: 0 + suspended: 0 + - apiVersion: source.toolkit.fluxcd.io/v1beta2 + kind: OCIRepository + stats: + failing: 0 + running: 1 + suspended: 0 + totalSize: 78.1 KiB + sync: + ready: true + source: https://github.com/controlplaneio-fluxcd/distribution.git + status: 'Applied revision: refs/heads/main@sha1:a90cd1ac35de01c175f7199315d3f4cd60195911' +status: + conditions: + - lastTransitionTime: "2024-06-20T19:59:30Z" + message: Reporting finished in 272ms + observedGeneration: 4 + reason: ReconciliationSucceeded + status: "True" + type: Ready +``` + +1. Export the report in YAML format: + + ```shell + kubectl -n flux-system get fluxreport/flux -o yaml + ``` + +2. Trigger a reconciliation of the report: + + ```shell + kubectl -n flux-system annotate --overwrite fluxreport/flux \ + reconcile.fluxcd.io/requestedAt="$(date +%s)" + ``` + +3. Change the report reconciliation interval: + + ```shell + kubectl -n flux-system annotate --overwrite fluxreport/flux \ + fluxcd.controlplane.io/reconcileEvery=5m + ``` + +4. Pause the report reconciliation: + + ```shell + kubectl -n flux-system annotate --overwrite fluxreport/flux \ + fluxcd.controlplane.io/reconcile=disabled + ``` + +5. Resume the reconciliation of the report: + + ```shell + kubectl -n flux-system annotate --overwrite fluxreport/flux \ + fluxcd.controlplane.io/reconcile=enabled + ``` + +## Reading a FluxReport + +As with all other Kubernetes config, a FluxReport is identified by `apiVersion`, +`kind`, and `metadata` fields. The `spec` field contains detailed information +about the Flux installation, including statistic data for the Flux custom resources +that are reconciled by the Flux controllers. + +### Distribution information + +The `.spec.distribution` field contains information about the Flux distribution, +including the version, installation status, entitlement issuer +and tool that is managing the distribution. + +Example distribution information for when Flux +was installed using the bootstrap command: + +```yaml +spec: + distribution: + entitlement: Issued by controlplane + managedBy: 'flux bootstrap' + status: Installed + version: v2.3.0 +``` + +### Components information + +The `.spec.components` field contains information about the Flux controllers, +including the controller name, the image repository, tag, and digest, and the +deployment readiness status. + +Example: + +```yaml +spec: + components: + - image: ghcr.io/fluxcd/kustomize-controller:v1.3.0@sha256:48a032574dd45c39750ba0f1488e6f1ae36756a38f40976a6b7a588d83acefc1 + name: kustomize-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' + - image: ghcr.io/fluxcd/source-controller:v1.3.0@sha256:161da425b16b64dda4b3cec2ba0f8d7442973aba29bb446db3b340626181a0bc + name: source-controller + ready: true + status: 'Current Deployment is available. Replicas: 1' +``` + +### Reconcilers statistics + +The `.spec.reconcilers` field contains statistics about the Flux custom resources +that are reconciled by the Flux controllers, including the API version, kind, and +the number of resources in each state: failing, running and suspended. +For source type resources, the storage size of the locally cached artifacts is also reported. + +Example: + +```yaml +spec: + reconcilers: + - apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + stats: + failing: 1 + running: 5 + suspended: 5 + - apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + stats: + failing: 1 + running: 2 + suspended: 3 + totalSize: 5.5 MiB +``` + +### Cluster sync status + +The `.spec.sync` field contains information about the Flux sync status, +including the source URL, the applied revision, and the sync readiness status. + +Example: + +```yaml +spec: + sync: + ready: true + source: https://github.com/controlplaneio-fluxcd/distribution.git + status: 'Applied revision: refs/heads/main@sha1:a90cd1ac35de01c175f7199315d3f4cd60195911' +``` + +### Reconciliation configuration + +The reconciliation behaviour can be configured using the following annotations: + +- `fluxcd.controlplane.io/reconcile`: Enable or disable the reconciliation loop. Default is `enabled`, set to `disabled` to pause the reconciliation. +- `fluxcd.controlplane.io/reconcileEvery`: Set the reconciliation interval. Default is `10m`.