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

Upgrade safety first

Before upgrading, inspect stored API versions and run:

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

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:

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

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 before choosing static credentials, controller identity, or object identity.

ArtifactGenerator workflows

Install the optional source-watcher component with:

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 <registry>/<name>:<tag>@<digest>. For resources that split image fields, use the :name, :tag, and :digest markers:

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.

Reactive configuration

To reconcile immediately when a referenced ConfigMap or Secret changes, label that object:

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:

flux trigger receiver

See notifications and Receivers for provider types, GitHub App and cloud authentication, GCR requirements, and event metadata behavior.

Debugging and operational tooling

Inspect fully merged configuration with:

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 for stable artifact commands, plugin lifecycle commands, and UI authentication details.