-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Stefan Prodan <[email protected]>
- Loading branch information
1 parent
9c3f391
commit 40f968b
Showing
2 changed files
with
269 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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`. |