Kustomization: reconciling

Apply and prune from a source.

Advanced12 min · lesson 4 of 12

The Flux Kustomization (distinct from Kustomize the tool, though it uses it) is the reconciler: it takes a source and a path within it, builds the manifests (running Kustomize if a kustomization.yaml is present, or applying plain YAML), and applies them to the cluster on an interval, pruning resources that were removed. It is the workhorse that turns “this Git path” into “these resources, kept in sync.”

THE KUSTOMIZATION RECONCILE LOOP

1Read source + path

sourceRef + path within it

2Build manifests

run Kustomize or apply plain YAML

3Apply to cluster

on the interval

4Prune removed

delete resources dropped from Git

5Wait for health

not Ready until workloads are healthy

Ready only when applied workloads are actually healthy, enabling dependency chains.

kustomization.yaml

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: { name: payments, namespace: flux-system }
spec:
  interval: 5m
  sourceRef: { kind: GitRepository, name: payments }
  path: ./k8s/overlays/prod
  prune: true                 # delete resources removed from Git
  wait: true                  # wait for applied resources to become ready
  targetNamespace: payments

Prune, wait, and health

Key fields: prune deletes resources that vanish from Git (like Argo CD prune), and wait makes Flux wait for the applied resources to become healthy before reporting success — so a Kustomization is not Ready until its workloads actually are. This health awareness is what lets you build dependency chains (next lesson). You reconcile on the interval automatically, or force it with flux reconcile for immediate feedback.

terminal

$ flux get kustomizations
NAME       REVISION      SUSPENDED  READY  MESSAGE
payments   v1.4.0/abc12  False      True   Applied revision v1.4.0
$ flux reconcile kustomization payments --with-source   # force a sync now

prune deletes what leaves Git — including stateful resources

With prune: true, removing a manifest from Git makes Flux delete the live resource on the next reconcile, which is correct for GitOps but dangerous for stateful objects if a refactor accidentally drops them. Review what a change would prune, protect critical resources (and their data) appropriately, and understand that in a pruning Kustomization, deletion from Git is deletion from the cluster.

Sources: GitRepository & moreHelmRelease & the helm-controller