FluxCD

The FluxCD plugin (fluxcd) monitors Flux Kustomizations and HelmReleases on a Kubernetes cluster. It shows the state of each resource, lists its reconciliation history and requests a reconciliation.

RequirementsCopy Anchor Link

The plugin reads the cluster through a kubeconfig and has no token field. The kubeconfig path points to a file on the machine that runs Pipedash. In the web app, that machine is the server and not the browser host.

The Kubernetes user in the kubeconfig needs these rights. The "Check permissions" button in the Add provider dialog tests each one with a SelfSubjectAccessReview and opens a "Kubernetes permissions" dialog.

With an empty namespaces value, Pipedash lists both kinds across the cluster. That needs list at cluster scope, so a ClusterRole and a ClusterRoleBinding. A namespace-scoped Role works when namespaces names those namespaces.

Validation fails when the cluster serves neither the Kustomization nor the HelmRelease API. If only one API exists, Pipedash lists that kind.

ConfigurationCopy Anchor Link

Namespace names use lowercase letters, numbers and hyphens, start and end with a letter or number, and have at most 63 characters. Pipedash drops duplicates. A selected resource outside namespaces makes the configuration invalid.

The pasted content in token suits devices that have no kubeconfig file, such as iOS and Android. On those systems, a kubeconfig user that authenticates through an exec credential plugin fails with an error. Examples are aws, gke-gcloud-auth-plugin and kubelogin. A token or a client certificate works there.

Cluster connectionCopy Anchor Link

FluxCD has no base URL. The kubeconfig supplies the API server and the credentials, and context picks the cluster entry. The plugin stops with an error when none of the listed kubeconfig paths exists.

Resource discoveryCopy Anchor Link

Pipedash lists Kustomizations and HelmReleases in each namespace from namespaces, or in all namespaces when the value is empty. Lists load in pages of 500 items.

The picker shows the namespace as the organization. Each entry has the name Kind/name and carries the path or chart and the source. Search matches the identity, name, source and description.

After the selection step, only the chosen resources appear. The list has the title "FluxCD resources" and groups them by source. A chosen resource that no longer exists stays in the list with the status pending and the label "Not found". The other resources keep refreshing.

A change to kubeconfig, context or namespaces in the Add provider dialog clears the saved selection. A new kubeconfig value also clears context. When editing a provider, the dialog says "Select resources again after changing connection scope." and disables "Save" until the user picks the resources again. Other edits, such as the credentials, keep the selection.

Supported kinds and API versionsCopy Anchor Link

Pipedash reads no other kind and no other API version.

ReconcileCopy Anchor Link

The "Reconcile" action replaces the Trigger action. It sits in the row menu of a resource, in the header of the history page and in the "Reconciliation details" dialog. The dialog "Reconcile: <resource>" has no parameters.

Pipedash sets the annotation reconcile.fluxcd.io/requestedAt on the resource to the current time, with the field manager pipedash. This needs the patch right. Flux processes the request asynchronously, so status and history update after the controller handles it.

• Configuration: A reconcile uses the current configuration of the resource. It does not restore the revision of a history record.
• Suspended resources: Pipedash refuses the request and never resumes or suspends a resource. The dialog tells the user to resume the resource in Flux first.
• Missing resources: The dialog says "This resource was not found. Update the selection or recreate it in Flux."
• Result: A notification titled "Reconciliation requested" follows a request. A failure shows "Couldn't request reconciliation".
• Cancel: Flux has no cancel for a reconciliation, and the plugin offers no cancel action.

A Reconcile request also clears the cached history of that resource. The next read fills it again from status.history.

Status mappingCopy Anchor Link

Pipedash applies these rules from top to bottom to the resource.

A condition counts only when its observedGeneration is at least metadata.generation. A Ready condition from an older generation reads as missing. The status is then pending with the reason StatusOutdated.

The status filter of the resource list offers Ready, Not ready, Reconciling, Pending and Suspended.

Each history record has its own status:

History and cacheCopy Anchor Link

Flux keeps a bounded status.history and groups repeated reconciliations. Pipedash builds the run history from it, so the history is not a full execution log. The history page says so with the note "FluxCD retains a limited reconciliation history. Repeated reconciliations may be grouped, and older entries may be unavailable."

• Kustomization: One record per history group, named "Reconciliation" with the first 7 characters of the revision digest. The record starts at lastReconciled minus lastReconciledDuration and ends at lastReconciled.
• HelmRelease: One record per history entry, named "Release #<version>". It starts at lastDeployed, or at firstDeployed when that is missing. Only the newest attempt has a duration.
• Current state: Pipedash adds a "Current state" record when the newest history record does not match the live state. Otherwise the newest record shows the current reason and message.

The history table shows the column "Recorded" in place of "Started" and sorts records by that time, newest first. A group that Flux reconciles again keeps its record, and the record moves up. The page shows "Flux has not recorded a reconciliation for this resource yet." for an empty history.

Unlike other providers, FluxCD keeps its run cache across refreshes. Pipedash keeps a finished record that Flux no longer reports, as long as the resource keeps the same uid. Such a record gets the suffix "(cached)" on its status, and its details dialog shows the alert "Cached reconciliation". Pipedash drops any other record that Flux no longer reports. These are running and pending records, current-state records and records of a recreated resource. Clearing the run history cache in Settings removes the kept records, as does a Reconcile request.

Metrics count finished history records. They update a grouped record without a second count. The current-state record is a snapshot and never enters metrics. A record that started before the metrics retention window does not enter metrics, so reading the history never recreates metrics outside that window. The Metrics and Cache pages cover both features.

Controller health and status pageCopy Anchor Link

Pipedash reads the deployments source-controller, kustomize-controller and helm-controller in flux_namespace. A deployment scaled to zero or with no available replica reports a major outage. A deployment with fewer available replicas than desired reports a degraded state. The provider status dialog lists these controllers under "Controllers".

status_page_url adds a custom status source. It takes an https URL without credentials, query or fragment. A literal loopback address may use http. Pipedash reads /api/v2/summary.json below that URL. The Provider health page covers both signals.

TOML exampleCopy Anchor Link

Without selected_items, Pipedash monitors every resource in the listed namespaces.

[providers.flux-prod]
name = "Flux Prod"
type = "fluxcd"
refresh_interval = 30

[providers.flux-prod.config]
kubeconfig = "~/.kube/config"
context = "prod-cluster"
namespaces = "flux-system,apps"
flux_namespace = "flux-system"
selected_items = "Kustomization__apps__web,HelmRelease__apps__api"

To paste the kubeconfig in place of a path, set the top-level token of the provider to the kubeconfig YAML.

Test environment with kindCopy Anchor Link

The folder examples/fluxcd holds manifests that run Flux in a kind cluster. They create healthy, failed and suspended Kustomizations and HelmReleases and a read-only service account for Pipedash. All sources use the podinfo Git tag 6.7.1 and the podinfo chart 6.7.1.

Create the clusterCopy Anchor Link

The config kind-cluster.yaml names the cluster pipedash-fluxcd and uses the node image kindest/node:v1.37.0.

DOCKER_CONTEXT=<ctx> KUBECONFIG=~/.kube/pipedash-fluxcd.kubeconfig \
  kind create cluster --config examples/fluxcd/kind-cluster.yaml
chmod 600 ~/.kube/pipedash-fluxcd.kubeconfig

The API server listens on 127.0.0.1:46443 of the Docker host only. For a remote Docker host, forward the port:

ssh -N -L 127.0.0.1:46443:127.0.0.1:46443 <docker-host>

Install Flux and the fixturesCopy Anchor Link

export KUBECONFIG=~/.kube/pipedash-fluxcd.kubeconfig
kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.9.6/install.yaml
kubectl -n flux-system wait --for=condition=Available deploy --all --timeout=300s
kubectl apply -k examples/fluxcd

The fixtures create these objects in the namespace pipedash-examples:

In the failed Kustomization, the path does not exist. The failed HelmRelease uses a nonexistent image tag and a 30-second timeout. Its controller message may describe an installation timeout and not the image pull failure.

The file rbac.yaml adds the service account pipedash-readonly. It has get and list on the two kinds in pipedash-examples and nothing else, so the optional rights in the permission dialog show as missing. The account has no token secret. A short-lived token comes from this command:

kubectl -n pipedash-examples create token pipedash-readonly --duration 1h

Connect PipedashCopy Anchor Link

1. Select "FluxCD" in the Add provider dialog.
2. Set "Kubeconfig" to the absolute path of ~/.kube/pipedash-fluxcd.kubeconfig on the machine that runs Pipedash.
3. Select the context kind-pipedash-fluxcd and enter the namespace pipedash-examples.
4. Select "Check permissions", continue to the resource selection and select the 6 examples.

The resource list shows the states Ready, Not ready and Suspended. Opening a resource shows the controller messages and the reconciliation history.

Check the clusterCopy Anchor Link

kubectl -n pipedash-examples get kustomizations,helmreleases
kubectl -n pipedash-examples annotate kustomization/podinfo-healthy --overwrite \
  reconcile.fluxcd.io/requestedAt="$(date +%s)"

The annotate command sets the annotation that "Reconcile" sets. The read-only service account cannot run it, because it has no patch right.

Standalone library checksCopy Anchor Link

The application that consumes the plugin chooses the Kubernetes API model of k8s-openapi. The environment variable K8S_OPENAPI_ENABLED_VERSION supplies that choice for a standalone check of the crate. The workspace model is 1.32.

K8S_OPENAPI_ENABLED_VERSION=1.32 cargo check -p pipedash-plugin-fluxcd --lib
K8S_OPENAPI_ENABLED_VERSION=1.32 cargo package -p pipedash-plugin-api -p pipedash-plugin-fluxcd

The package command names both crates. This makes the verification use the plugin API from the checkout and not its previously published version. The CI and release workflows set the same variable when they package and publish the plugin crates.