Skip to content

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 was deployed:

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:
kubectl -n flux-system get fluxreport/flux -o yaml
  1. Trigger a reconciliation of the report:
kubectl -n flux-system annotate --overwrite fluxreport/flux \
 reconcile.fluxcd.io/requestedAt="$(date +%s)"
  1. Change the report reconciliation interval:
kubectl -n flux-system annotate --overwrite fluxreport/flux \
 fluxcd.controlplane.io/reconcileEvery=5m
  1. Pause the report reconciliation:
kubectl -n flux-system annotate --overwrite fluxreport/flux \
 fluxcd.controlplane.io/reconcile=disabled
  1. 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:

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:

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:

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:

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 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 5m.

The default reconciliation interval of the report can be changed by setting the REPORTING_INTERVAL environment variable in the operator deployment.

Flux Resource Metrics

The Flux Operator exports metrics for all Flux resources found in the cluster. These metrics are refreshed at the same time with the update of the FluxReport.

Metrics:

flux_resource_info{uid, kind, name, exported_namespace, ready, suspended, ...}

Common labels:

  • uid: The Kubernetes unique identifier of the resource.
  • kind: The kind of the resource (e.g. GitRepository, Kustomization, etc.).
  • name: The name of the resource (e.g. flux-system).
  • exported_namespace: The namespace of the resource (e.g. flux-system).
  • ready: The readiness status of the resource (e.g. True, False or Unkown).
  • reason: The reason for the readiness status (e.g. Progressing, BuildFailed, HealthCheckFailed, etc.).
  • suspended: The suspended status of the resource (e.g. True or False).

Specific labels per resource kind:

Resource Kind Labels
Kustomization revision, source_name, path
GitRepository revision, url, ref
OCIRepository revision, url, ref
Bucket revision, url, ref
HelmRelease revision, source_name
HelmChart revision, source_name
HelmRepository revision, url
Receiver url
ImageRepository url
ImagePolicy source_name
ImageUpdateAutomation source_name

Example:

flux_resource_info{
    exported_namespace="flux-system",
    kind="Kustomization",
    name="flux-system",
    path="production/clusters",
    ready="True",
    reason="ReconciliationSucceeded",
    revision="refs/heads/main@sha1:d3c6dfa21465cc540d214811f46694fee0ce700d",
    source_name="flux-system",
    suspended="False",
    uid="359219f3-0793-4cf0-89a1-990ef1ac8098"
}