# Flux CD Knowledge Patch > Flux CD - Skill: `nevaberry/flux-cd-knowledge-patch` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add nevaberry/flux-cd-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/flux-cd-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/flux-cd-knowledge-patch --- # Flux CD Knowledge Patch Use this skill when writing, reviewing, migrating, or troubleshooting Flux manifests, controller flags, CLI workflows, source authentication, image automation, notification delivery, or Flux Operator installations. Prefer the project's installed CRDs, controller versions, manifests, and live behavior when they disagree with this guidance. Flux controllers and CRDs are upgraded as a coordinated set, and feature gates must be enabled on the controller that implements the feature. ## Reference index | Reference | Topics | | --- | --- | | [CLI and Operator](references/cli-and-operator.md) | Debug commands, artifact commands, plugins, migrations, Operator UI | | [Image automation](references/image-automation.md) | Stable APIs, digest pinning, cloud auth, commit templates, refspec safety | | [Kustomizations and Helm](references/kustomizations-and-helm.md) | Health, apply, deletion, SOPS, values, dependencies, retries, inventory | | [Notifications and Receivers](references/notifications-and-receivers.md) | Event metadata, commit statuses, comments, transports, traces, webhook auth | | [Sources, auth, and artifacts](references/sources-auth-and-artifacts.md) | Git and OCI sources, Workload Identity, verification, ArtifactGenerator | | [Upgrades and platforms](references/upgrades-and-platforms.md) | Required migrations, removed APIs, CRD coordination, support windows | ## Upgrade safety first Before upgrading, inspect stored API versions and run: ```shell flux migrate ``` The 2.7, 2.8, and 2.9 CRDs remove successive beta APIs. A manifest's current `apiVersion` does not prove that the object stored in etcd has been migrated. Read [upgrades and platforms](references/upgrades-and-platforms.md) for the exact removed versions. Upgrade CRDs with their controllers. This is especially important when using `ArtifactGenerator` or `ImageUpdateAutomation`, whose schemas changed in a 2.9 maintenance release. Repository manifests can be migrated with `flux migrate -f` where supported. ### Breaking Helm post-render behavior The HelmRelease post-render default is `combined`, so hooks pass through post-rendering. A chart that requires the former behavior must explicitly use `nohooks` before the controller upgrade. ### Image automation refspec restrictions Remove force-update and ref-deletion operations from `ImageUpdateAutomation` refspecs. They are rejected by current controllers. ### Registry provider validation For `OCIRepository` and `ImageRepository`, set `spec.provider` to `aws`, `azure`, or `gcp` only when the registry URL matches and automatic OIDC is intended. For public registries and pull-secret authentication, omit it or use `generic`. ## Kustomization health and ownership Use `spec.healthCheckExprs` to teach Flux readiness semantics for custom resources. Select the API version and kind, then define CEL `failed` and `current` expressions. With `wait: true`, dependents wait until resources are current. ```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')" ``` For an API-group-wide rule, omit `kind`. Dependency entries in `Kustomization.spec.dependsOn` and `HelmRelease.spec.dependsOn` can also use CEL readiness expressions. Use `Kustomization.spec.ignore` when another controller owns selected fields: ```yaml spec: ignore: - target: kind: Deployment paths: - /spec/replicas ``` This keeps fields such as HPA-managed replicas out of drift detection and apply. See [Kustomizations and Helm](references/kustomizations-and-helm.md) for deletion policies, apply staging, decryption, and feature-gate interactions. ## Helm reconciliation defaults New Helm releases use Helm v4 server-side apply and kstatus health checks. Existing stored releases continue with client-side apply until opted in. Use the `UseHelm3Defaults` feature gate only when the previous apply and health behavior is required. For quicker recovery, enable `CancelHealthCheckOnNewRevision` on helm-controller together with `DefaultToRetryOnFailure`. Cancellation can be caused by source or spec changes, watched ConfigMaps or Secrets, manual reconciliation, or Receiver triggers, and reports `HealthCheckCanceled`. Use `RetryOnFailure` for install and upgrade retries. Inspect `HelmRelease.status.inventory` to see the managed object set. `HelmRelease.valuesFrom` literal mode treats the entire referenced key as one string, matching `helm install --set-literal`; it does not parse types or expand dotted property names. ## Source and identity choices Use the stable `source.toolkit.fluxcd.io/v1` API for `OCIRepository`; migration from `v1beta2` requires only an `apiVersion` change. Git repositories support directory-based sparse checkout, HTTPS mutual TLS, GitHub App authentication, and several object-level Workload Identity paths. Create GitHub App credentials with: ```shell flux create secret githubapp github-auth \ --app-id=1 \ --app-installation-id=2 \ --app-private-key=~/private-key.pem ``` Reference the Secret through `spec.secretRef.name`. Supported flows can look up the installation ID from the repository owner, so it need not always be provided. Read [sources, auth, and artifacts](references/sources-auth-and-artifacts.md) before choosing static credentials, controller identity, or object identity. ## ArtifactGenerator workflows Install the optional source-watcher component with: ```shell flux bootstrap ... --components-extra=source-watcher ``` `ArtifactGenerator` can combine Git, OCI, and Bucket content, split a monorepo into independently revised `ExternalArtifact` objects, and extract or modify Helm charts. `spec.pathPattern` discovers matching directories; named captures become variables in artifact names, labels, and copy rules. Point a `Kustomization` source or a `HelmRelease.spec.chartRef` at an `ExternalArtifact`. Path-specific outputs prevent unrelated monorepo changes from triggering every deployment. ## Image digest pinning Set `ImagePolicy.spec.digestReflectionPolicy: Always` to track the latest digest. Image automation can then write `/:@`. For resources that split image fields, use the `:name`, `:tag`, and `:digest` markers: ```yaml image: repository: docker.io/my-org/my-app # {"$imagepolicy": "flux-system:my-app:name"} tag: latest # {"$imagepolicy": "flux-system:my-app:tag"} digest: sha256:ec0119... # {"$imagepolicy": "flux-system:my-app:digest"} ``` The image APIs are stable at `image.toolkit.fluxcd.io/v1`. Update old commit templates away from removed `.Updated` and `.Changed.ImageResult` fields. Details are in [image automation](references/image-automation.md). ## Reactive configuration To reconcile immediately when a referenced ConfigMap or Secret changes, label that object: ```yaml metadata: labels: reconcile.fluxcd.io/watch: Enabled ``` Alternatively, configure the relevant controller with `--watch-configs-label-selector=owner!=helm`. This applies to supported Kustomization, HelmRelease, and Receiver references; consult the detailed reference for the exact fields. ## Notifications, status, and Receivers Flux object annotations can enrich notification events. Use `event.toolkit.fluxcd.io/commit` for commit status providers and `event.toolkit.fluxcd.io/change_request` for pull or merge request comment providers. Comment providers update a deduplicated deployment-status comment without an intermediary CI workflow. `Provider.spec.commitStatusExpr` can derive per-cluster or per-tenant status identifiers with CEL. `proxySecretRef` and `certSecretRef` supply proxy and mutual-TLS material. A Provider of type `otel` converts reconciliation events into related source-rooted traces. Receivers can filter resources with CEL. Generic Receivers can validate an OIDC ID token instead of an HMAC shared secret and can be invoked with: ```shell flux trigger receiver ``` See [notifications and Receivers](references/notifications-and-receivers.md) for provider types, GitHub App and cloud authentication, GCR requirements, and event metadata behavior. ## Debugging and operational tooling Inspect fully merged configuration with: ```shell flux debug kustomization --show-vars flux debug helmrelease --show-values ``` These commands print referenced Secret values in clear text. Treat terminal output, logs, and captured transcripts as sensitive. The CLI supports independently versioned plugins under `~/fluxcd/plugins`. Pin versions or immutable digests in reproducible automation. The Flux Operator UI provides GitOps rollout views, workload dashboards, multi-pod and multi-container logs, and RBAC-guarded actions using user impersonation. Read [CLI and Operator](references/cli-and-operator.md) for stable artifact commands, plugin lifecycle commands, and UI authentication details.