From b88223cbfd17bd3a03a87de06f4ee516a8803c87 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Sat, 22 Jun 2024 15:53:53 +0300 Subject: [PATCH] Update docs for flux-operator v0.6.0 Signed-off-by: Stefan Prodan --- docs/distribution/index.md | 19 ++- docs/marketplace/aws.md | 7 +- docs/operator/fluxinstance.md | 4 +- docs/operator/fluxreport.md | 266 ++++++++++++++++++++++++++++++++++ docs/operator/monitoring.md | 38 +++++ mkdocs.yml | 3 + 6 files changed, 331 insertions(+), 6 deletions(-) create mode 100644 docs/operator/fluxreport.md create mode 100644 docs/operator/monitoring.md diff --git a/docs/distribution/index.md b/docs/distribution/index.md index c53d3dc..75fd322 100644 --- a/docs/distribution/index.md +++ b/docs/distribution/index.md @@ -47,7 +47,7 @@ The ControlPlane distribution comes with enterprise-hardened Flux controllers in !!! tip "Flux Operator" To streamline the deployment of the enterprise distribution, the ControlPlane team - created the [Flux Operator](../operator). The operator manages the lifecycle of the + created the [Flux Operator](../operator/index.md). The operator manages the lifecycle of the Flux controllers and automates the upgrade process, including the patching of hotfixes and CVEs affecting Flux functionality. @@ -82,3 +82,20 @@ images fully compatible with the upstream Flux feature set. The major difference between the Flux upstream images and the ControlPlane mainline images is the continuous scanning and CVE patching for the container base images, OS packages, and Go dependencies. + +## Distribution Components + +The Controlplane distribution comprises Open Source components such as the CNCF +[Flux controllers](../guides/flux-architecture.md#flux-controllers) (Apache 2.0 License) +and the [Flux Operator](../operator/index.md) (AGPL-3.0 License). + +!!! note "Delivery Pipeline" + + The build, test and release pipeline developed by [ControlPlane](https://control-plane.io) + is compliant with the [SLSA](security.md) security framework. + + The ControlPlane build system produces FIPS-compliant binaries, + multi-arch container images, generates SBOMs, applies CVE patches + & hotfixes to the Open Source components, and runs conformance tests. + The resulting container images and SBOMs are hosted on private registries + that are only available to customers with a valid subscription. diff --git a/docs/marketplace/aws.md b/docs/marketplace/aws.md index 27fdc67..e94fd29 100644 --- a/docs/marketplace/aws.md +++ b/docs/marketplace/aws.md @@ -35,11 +35,12 @@ helm upgrade -i flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-op ``` To verify that the AWS Marketplace entitlement is valid, -check the logs of the `flux-operator` pod: +check the report generated in the `flux-system` namespace: ```console -$ kubectl -n flux-system logs -l app.kubernetes.io/name=flux-operator -{"level":"info","msg":"Entitlement verified","vendor":"controlplane-aws"} +$ kubectl -n flux-system get fluxreport/flux -o wide +NAME ENTITLEMENT AGE READY STATUS +flux Issued by controlplane-aws 1m True Reporting finished in 34ms ``` ## Flux Installation Options diff --git a/docs/operator/fluxinstance.md b/docs/operator/fluxinstance.md index ebae01b..c38c3c8 100644 --- a/docs/operator/fluxinstance.md +++ b/docs/operator/fluxinstance.md @@ -11,7 +11,7 @@ where the flux-operator is deployed. The following example shows a FluxInstance custom resource that installs the upstream Flux distribution with all available components, -and configures the flux-operator to automatically upgrade Flux +and configures the flux-operator to automatically upgrade Flux to the latest stable version: ```yaml @@ -640,7 +640,7 @@ Status: `.status.lastAppliedRevision` is the last revision of the Flux distribution that was successfully applied to the cluster. -The revision is in the format `@sha256:`. +The revision is in the format `@sha256:`. The version is the Flux distribution exact semver version that was applied to the cluster. diff --git a/docs/operator/fluxreport.md b/docs/operator/fluxreport.md new file mode 100644 index 0000000..70a249b --- /dev/null +++ b/docs/operator/fluxreport.md @@ -0,0 +1,266 @@ +# 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 + id: kustomization/flux-system + path: clusters/production + source: https://github.com/my-org/my-fleet.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 cluster sync status, +including the Flux Kustomization name, source URL, the applied revision, +and the sync readiness status. + +Example: + +```yaml +spec: + sync: + ready: true + id: kustomization/flux-system + path: tests/v2.3/sources + source: https://github.com/controlplaneio-fluxcd/distribution.git + status: 'Applied revision: refs/heads/main@sha1:a90cd1ac35de01c175f7199315d3f4cd60195911' +``` + +## Generating a FluxReport + +The FluxReport is automatically generated by the operator for the following conditions: + +- At startup, when the operator is installed or upgraded. +- When the [FluxInstance](fluxinstance.md) is created or updated. +- When the `reconcile.fluxcd.io/requestedAt` annotation is set on the FluxReport resource. +- At regular intervals, controlled by the `fluxcd.controlplane.io/reconcileEvery` annotation. + +### 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`. diff --git a/docs/operator/monitoring.md b/docs/operator/monitoring.md new file mode 100644 index 0000000..caf09f2 --- /dev/null +++ b/docs/operator/monitoring.md @@ -0,0 +1,38 @@ +# Flux Monitoring and Troubleshooting + +## Flux Status Reporting + +The Flux Operator automatically generates a report that reflects the observed state of the Flux +installation. The report provides information about the installed components and their readiness, +the Flux distribution details, reconcilers statistics, cluster sync status and more. + +The report is generated as a custom resource of kind `FluxReport`, named `flux`, +located in the same namespace where the operator the running. + +To view the report in YAML format run: + +```shell +kubectl -n flux-system get fluxreport/flux -o yaml +``` + +The operator updates the report at regular intervals, by default every 10 minutes. +To manually trigger a reconciliation of the report, run: + +```shell +kubectl -n flux-system annotate --overwrite fluxreport/flux \ + reconcile.fluxcd.io/requestedAt="$(date +%s)" +``` + +Find more information about the reporting features +in the [Flux Report API documentation](fluxreport.md). + +## Flux Instance Events + +The Flux Operator emits events to the Kubernetes API server to report on the status of the Flux +instance. The events are useful to monitor the Flux lifecycle and troubleshoot issues. + +To list the events related to the Flux instance, run: + +```shell +kubectl -n flux-system events for fluxinsance/flux +``` diff --git a/mkdocs.yml b/mkdocs.yml index 3c25aca..c856314 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,8 +104,11 @@ nav: - Flux Controllers: operator/flux-config.md - Flux Cluster Sync: operator/flux-sync.md - Flux Customization: operator/flux-kustomize.md + - Guides: + - Monitoring and Troubleshooting: operator/monitoring.md - Bootstrap Migration: operator/flux-bootstrap-migration.md - API Reference: - Flux Instance: operator/fluxinstance.md + - Flux Report: operator/fluxreport.md - Pricing: pricing/index.md - Contact: https://control-plane.io/contact/?inquiry=fluxcd