Skip to content
Kubernetes Template

Managing Flux Kustomizations

Kustomizations vs Kustomize

Section titled “Kustomizations vs Kustomize”

Flux introduces a custom resource also named Kustomization (API group kustomize.toolkit.fluxcd.io). This CRD is what Flux watches — it holds a source reference, a path, a sync interval, and optional decryption config. Kustomize (the tool, kubectl kustomize) is what Flux runs against that path to produce plain manifests.

The two concepts share a name but sit at different layers:

  • Flux Kustomization — a Kubernetes object in flux-system that drives continuous delivery.
  • Kustomize overlay — a kustomization.yaml file on disk that patches base manifests for an environment.

Flux evaluates the overlay and applies the result to the cluster. Editing a kustomization.yaml on disk changes what gets deployed; editing the Flux Kustomization CRD changes how Flux syncs it.

The Kustomization Hierarchy

Section titled “The Kustomization Hierarchy”

The local cluster uses three Flux Kustomizations arranged in a dependency chain:

flux-system  →  infrastructure  →  (apps)

flux-system is the bootstrap Kustomization. Flux generates it in clusters/local/flux-system/gotk-sync.yaml. It watches ./clusters/local on the main branch and syncs every 10 minutes. This is the root — it creates all other Kustomizations by applying whatever manifests live in that path.

infrastructure is defined in clusters/local/infrastructure.yaml. It points to ./infrastructure/overlays/local, syncs every 10 minutes, and prunes removed resources. It carries SOPS decryption config so that encrypted secrets in the infrastructure overlay are decrypted at apply time using the sops-age secret.

apps would sit at the next tier, depending on infrastructure being healthy before it syncs.

SOPS Decryption

Section titled “SOPS Decryption”

The infrastructure Kustomization references a decryption provider and key secret:

spec:
  decryption:
    provider: sops
    secretRef:
      name: sops-age

Flux passes each encrypted file through sops --decrypt before applying it. The sops-age secret must exist in flux-system and contain the Age private key. Without it, any manifest encrypted with SOPS will fail to apply and Flux will report a decryption error on the infrastructure Kustomization.

Managing Kustomizations with kb flux

Section titled “Managing Kustomizations with kb flux”

The kb flux subcommands wrap the Flux CLI to handle common day-to-day operations.

Pause all kustomizations

Section titled “Pause all kustomizations”
Terminal window
kb flux pause

Suspends every Kustomization in flux-system. Flux stops reconciling — it will not push changes from Git or revert manual edits to the cluster. Use this when you need to apply temporary changes without Flux fighting you.

Resume all kustomizations

Section titled “Resume all kustomizations”
Terminal window
kb flux resume

Lifts suspension on all Kustomizations. Flux resumes its polling loop and will reconcile on the next interval.

Force reconciliation

Section titled “Force reconciliation”
Terminal window
kb flux reconcile [name]

Triggers an immediate reconcile for a single Kustomization without waiting for the next interval. The default target is infrastructure:

Terminal window
kb flux reconcile
kb flux reconcile flux-system
kb flux reconcile apps

This is equivalent to flux reconcile kustomization <name> -n flux-system. Use it after pushing a change to Git when you don’t want to wait up to 10 minutes for the normal poll.

Checking Status

Section titled “Checking Status”

To inspect Kustomization health directly with the Flux CLI:

Terminal window
flux get kustomizations -n flux-system

Each row shows the last applied revision, whether reconciliation is suspended, and the ready condition. A False ready status with an error message usually indicates either a missing SOPS key, a path that doesn’t exist in the repository, or a resource that failed to apply.