flux-cd-knowledge-patch

# Flux CD Knowledge Patch Use this skill when changing Flux manifests, controller flags, authentication, artifact pipelines, notification integrations, or upgrade procedures. Inspect the installed Flux and Kubernetes versions before applying version-dependent advice, and prefer the cluster's CRDs, manifests, and observed controller behavior when they differ from this guidance. ## Reference index | Reference | Topics | | --- | --- | | [Helm releases](references/helm-releases.md) | Helm v4 behavior, retries, values, inventory, health checks, and chart processing | | [Identity and operations](references/identity-and-operations.md) | GitHub Apps, Workload Identity, SOPS key services, UI operations, and CLI plugins | | [Image automation](references/image-automation.md) | Stable image APIs, digest pinning, commit templates, signing, and refspec restrictions | | [Kustomizations](references/kustomizations.md) | CEL health, deletion, reconciliation watches, SOPS, apply ordering, and ignored fields | | [Notifications and Receivers](references/notifications-and-receivers.md) | Event metadata, commit status, pull-request comments, OTel, provider transport, and Receiver security | | [Sources and artifacts](references/sources-and-artifacts.md) | OCI APIs, artifact commands, Git access, verification, ArtifactGenerator, and ExternalArtifact | | [Upgrades and platforms](references/upgrades-and-platforms.md) | Required migrations, CRD coordination, supported platforms, and end-of-life windows | ## Start with upgrade blockers ### Migrate stored APIs before controller upgrades Run `flux migrate` before an upgrade whose CRDs remove an API version. The key removal boundaries are: - Flux 2.7 removes the `v1beta1` source, Kustomize, Helm, image, and notification APIs listed in the upgrade reference. - Flux 2.8 removes `source.toolkit.fluxcd.io/v1beta2`, `kustomize.toolkit.fluxcd.io/v1beta2`, and `helm.toolkit.fluxcd.io/v2beta2`. - Flux 2.9 removes `image.toolkit.fluxcd.io/v1beta2` and `notification.toolkit.fluxcd.io/v1beta2`. GCR Receiver Secrets must also contain `email` and `audience`. For Flux 2.9 repository manifests, use `flux migrate -f`. When deploying Flux 2.9.4, update the `ArtifactGenerator` and `ImageUpdateAutomation` CRDs together with their controllers. GCS static authentication accepts only service-account keys, and `MigrateAPIVersion` is available to repair API versions in managed-field entries. ### Account for Helm behavior changes Flux 2.8 ships Helm v4. New releases use server-side apply; releases already stored by Helm remain on client-side apply until explicitly opted in. Kstatus-based health checks become the default for every HelmRelease. Enable `UseHelm3Defaults` to retain the prior apply and health behavior. Flux 2.9 changes the default post-render strategy from `nohooks` to `combined`, which sends Helm hooks through post-rendering. Set the strategy to `nohooks` before upgrading if a chart depends on the old behavior. ### Update image automation assumptions The image APIs are stable at `image.toolkit.fluxcd.io/v1`. Before moving to Flux 2.7, replace removed image-reflector `autologin` flags with `ImageRepository.spec.provider`, and replace commit-template uses of `.Updated` or `.Changed.ImageResult` with `.Changed.FileChanges`, `.Changed.Objects`, or the flat `.Changed.Changes` list. Flux 2.9.4 rejects `ImageUpdateAutomation` refspecs that force-update or delete refs. Remove those operations before upgrading. Source-controller and image-reflector-controller support GCP sovereign-cloud artifact registries. ## High-value Helm release controls Use `RetryOnFailure` for install or upgrade retry behavior. If enabling `CancelHealthCheckOnNewRevision` for helm-controller, also enable `DefaultToRetryOnFailure`; otherwise a canceled health check can leave a release stuck with the default no-retry configuration. A cancellation reports `HealthCheckCanceled` on the `Ready` condition. `HelmRelease.valuesFrom` supports literal mode: the full contents of a selected ConfigMap or Secret key become one string, like `helm install --set-literal`, without parsing types or expanding dotted names. Use `.status.inventory` to inspect all objects managed by a HelmRelease. To see the final merged values, run: ```shell flux debug helmrelease --show-values ``` The command prints referenced Secret values in clear text. Treat its output as sensitive. ## High-value Kustomization controls ### Teach readiness with CEL Use `Kustomization.spec.healthCheckExprs` when a custom resource does not follow standard Kubernetes readiness conventions: ```yaml spec: wait: true healthCheckExprs: - apiVersion: cluster.x-k8s.io/v1beta1 kind: Cluster failed: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'False')" current: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')" ``` Health expressions for Kustomizations and HelmReleases can leave `kind` empty to apply one expression across every kind in an API group. Dependency entries in both resources can also use CEL to extend normal Ready-condition checks. ### Control deletion and field ownership `Kustomization.spec.deletionPolicy` controls garbage collection. Select `WaitForTermination` when deletion of the Kustomization must wait for all managed resources to disappear. Use `Kustomization.spec.ignore` to keep selected managed fields out of both drift detection and apply, for example when an HPA owns replicas: ```yaml spec: ignore: - target: kind: Deployment paths: - /spec/replicas ``` ### Reconcile watched inputs immediately Opt a referenced ConfigMap or Secret into immediate reconciliation with: ```yaml metadata: labels: reconcile.fluxcd.io/watch: Enabled ``` The controller-wide alternative is `--watch-configs-label-selector=owner!=helm`. The supported Kustomization, HelmRelease, and Receiver reference fields are listed in their topic files. ## Sources and generated artifacts `OCIRepository` is stable at `source.toolkit.fluxcd.io/v1` and is backward compatible with `v1beta2`, so that migration only requires changing `apiVersion`. Artifact build, push, pull, tag, diff, and list commands and the Flux config/content media types are stable. For `OCIRepository` and `ImageRepository`, use `aws`, `azure`, or `gcp` as `.spec.provider` only when the repository URL matches that cloud registry and automatic OIDC authentication is intended. For public repositories or image-pull Secrets, omit the provider or set it to `generic`. Enable source-watcher with `--components-extra=source-watcher` to use `ArtifactGenerator` and `ExternalArtifact`. Generators can compose sources, split monorepos, process Helm charts, and discover directories through `spec.pathPattern`; only changed path-specific artifacts need to trigger their consumers. ## Authentication quick reference Create a GitHub App Secret with: ```shell flux create secret githubapp github-auth \ --app-id=1 \ --app-installation-id=2 \ --app-private-key=~/private-key.pem ``` Reference it through `.spec.secretRef.name` on a `GitRepository` or `ImageUpdateAutomation`. `flux create source git --provider=github` supports the same mode. Later authentication flows can look up the installation ID from the repository owner, and GitRepository GitHub App authentication can use mutual TLS. Enable `ObjectLevelWorkloadIdentity` before assigning per-object identities. It supports Kustomization SOPS/KMS decryption and registry access by OCIRepository or ImageRepository, with broader Bucket, GitRepository, notification Provider, remote-cluster, Vault, and OpenBao cases detailed in the operations reference. ## Notifications and Receivers Use `event.toolkit.fluxcd.io/image`, `change_request`, and `commit` annotations to add the image reference or change identifier needed by downstream providers. CEL can filter Receiver targets, derive custom commit-status IDs, and distinguish clusters in monorepos. Generic Receivers can validate an OIDC ID token instead of an HMAC secret. Use `flux trigger receiver` to invoke one without manually constructing a webhook request. An `otel` Provider translates source events into root spans and consuming Kustomization or HelmRelease events into child spans. Pull- and merge-request comment providers publish deduplicated deployment-status comments directly; commit-status reporting accepts events from any Flux API. ## Operational checks - Use `flux debug kustomization --show-vars` to inspect merged substitutions; its referenced Secret values are clear text and must be protected. - Pin Flux CLI plugin versions or immutable digests in reproducible workflows. Manage plugins with `flux plugin search`, `install`, `list`, `update`, and `uninstall`. - Check the Kubernetes and OpenShift support matrix before an upgrade. Flux supports only the latest three Kubernetes minor versions. - Verify CRDs and controllers were deployed as one coordinated change when a release changes schemas.