The Flux Kustomization CRD (kustomize.toolkit.fluxcd.io/v1) is managed by kustomize-controller. It is Flux's primary mechanism for deploying manifests to a cluster.

This is distinct from Kustomize's kustomization.yaml config file — they share the name but are different resources.

Minimal example

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 10m
  prune: true
  sourceRef:
    kind: OCIRepository     # GitRepository | OCIRepository | Bucket | ExternalArtifact
    name: fleet-manifests
  path: ./apps
  wait: true
  timeout: 5m
  serviceAccountName: apps-reconciler    # for multi-tenant RBAC isolation

Core fields

Field	Required	Purpose
`sourceRef.kind`	Yes	`GitRepository`, `OCIRepository`, `Bucket`, `ExternalArtifact`
`sourceRef.name`	Yes	Name of the source object
`interval`	Yes	How often to reconcile
`prune`	Yes	Delete resources removed from source
`path`	No	Subdirectory within the artifact
`targetNamespace`	No	Override namespace for all resources
`wait`	No	Block until resources are Ready (default: false)
`timeout`	No	Fail fast if blocked (default: 5m)
`force`	No	Recreate resources that can't be patched
`suspend`	No	Pause reconciliation
`deletionPolicy`	No	`MirrorPrune` (default), `WaitForTermination`
`serviceAccountName`	No	Impersonate this SA for RBAC isolation

Dependencies

Kustomizations wait until dependencies are Ready before reconciling:

spec:
  dependsOn:
    - name: infrastructure
      namespace: flux-system
    - name: cert-manager
      namespace: flux-system
      readyExpr: >
        status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')

readyExpr is a CEL expression with access to dep (the dependency object) and self (this Kustomization). Use status.observedGeneration >= 0 as a "reconciled-once" check for CRD-installing Kustomizations.

PostBuild variable substitution

${VAR} placeholders are replaced after kustomize build but before apply. Variables are sourced from inline substitute map or ConfigMaps/Secrets via substituteFrom.

spec:
  postBuild:
    substitute:
      CLUSTER_NAME: "production-eu"
      REPLICA_COUNT: "3"
    substituteFrom:
      - kind: ConfigMap
        name: flux-runtime-info    # label: reconcile.fluxcd.io/watch: Enabled
        optional: false
      - kind: Secret
        name: cluster-secrets
        optional: true

Rules:

Inline substitute values take precedence over substituteFrom
Escape a literal ${VAR} with $$ → $${VAR}
Only substitutes within this Kustomization's own path — add substituteFrom to the Kustomization that owns the manifest, not a sibling

SOPS decryption

spec:
  decryption:
    provider: sops
    secretRef:
      name: sops-age    # key: age.agekey

Without secretRef, Cloud KMS with workload identity is used (GCP, AWS, Azure).

Health checks

When wait: true, standard Kubernetes readiness conditions are evaluated. Custom CEL expressions override the built-in check:

spec:
  healthCheckExprs:
    - apiVersion: apps/v1
      kind: Deployment
      current: >
        object.status.conditions.filter(e, e.type == 'Available').all(e, e.status == 'True')
      inProgress: >
        object.status.conditions.filter(e, e.type == 'Progressing').exists(e, e.status == 'True')
      failed: >
        object.status.replicas > 0 && object.status.readyReplicas == 0

Remote cluster deployment

Secret-based (static kubeconfig):

spec:
  kubeConfig:
    secretRef:
      name: remote-cluster-kubeconfig
      key: value

Secretless (workload identity):

spec:
  kubeConfig:
    secretRef:
      name: remote-cluster-config
  # Secret contains provider fields: aws | azure | gcp | generic

When both kubeConfig and serviceAccountName are set, the controller impersonates the service account on the remote cluster.

Apply behaviour annotations

Flux uses server-side apply (SSA). Per-resource annotations tune field ownership:

Annotation	Value	Behaviour
`kustomize.toolkit.fluxcd.io/ssa`	`Override`	Flux owns all fields; reverts external edits (default)
`kustomize.toolkit.fluxcd.io/ssa`	`Merge`	Preserves non-overlapping fields from other tools (Terraform co-ownership)
`kustomize.toolkit.fluxcd.io/ssa`	`IfNotPresent`	Only creates if absent — never updates
`kustomize.toolkit.fluxcd.io/ssa`	`Ignore`	Skips this resource entirely
`kustomize.toolkit.fluxcd.io/force`	`Enabled`	Recreates on immutable field changes
`kustomize.toolkit.fluxcd.io/prune`	`Disabled`	Protects from garbage collection

Status and inventory

Managed resources are tracked in status.inventory using the format:

<namespace>_<name>_<group>_<kind>

This inventory powers prune: true — resources present in the inventory but absent from the current build are deleted.

Reconciliation triggers

# Force immediate reconciliation (fetches source first)
flux reconcile kustomization apps --with-source -n flux-system

# Annotate directly
kubectl annotate kustomization apps -n flux-system \
  reconcile.fluxcd.io/requestedAt="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite

Validation

# Status overview
flux get kustomizations -A

# Detailed status with events
kubectl describe kustomization apps -n flux-system

# Logs for reconciliation errors
flux logs --kind=Kustomization --name=apps --namespace=flux-system

# List managed inventory
kubectl get kustomization apps -n flux-system -o jsonpath='{.status.inventory.entries[*]}' | tr ' ' '\n'

Retry interval

Configure retryInterval to recover faster from transient failures without waiting the full interval:

spec:
  interval: 30m
  retryInterval: 5m    # retry every 5m on failure instead of waiting 30m

Without retryInterval, a failed Kustomization waits the full spec.interval before the next attempt.

Common mistakes

Mistake	Correct approach
`substituteFrom` on a sibling Kustomization	Add `substituteFrom` to the Kustomization that owns the manifest
`wait: false` with `dependsOn`	Dependency checks are only meaningful when `wait: true`
`prune: true` without testing	Verify `status.inventory` before enabling — garbage collection is immediate
Manual edit of a Flux-managed resource	Flux reverts on next reconciliation — add `ssa: Merge` annotation if co-ownership is needed
No `retryInterval` set	Flux waits the full `spec.interval` between failure retries — set `retryInterval: 5m`