What is the Kustomization controller in FluxCD and how does it apply manifests to the cluster?

Think of the Kustomization controller as a general contractor who takes blueprints (manifests from a source) and builds the actual structure (deploys resources to the cluster). The contractor does not just blindly follow blueprints; they check that each phase of construction is complete before starting the next (health checks), remove old structures that are no longer in the plans (pruning), and can customize blueprints for different sites (variable substitution).

The Flux Kustomization controller (not to be confused with the Kustomize tool itself) is one of the core controllers installed during Flux bootstrap. It watches Kustomization custom resources (defined in the kustomize.toolkit.fluxcd.io API group) and applies the Kubernetes manifests they reference. Each Kustomization resource points to a source (typically a GitRepository) and a path within that source. When the source produces a new artifact (because a new commit was detected), the Kustomization controller extracts the manifests from the specified path, optionally runs Kustomize to process overlays and patches, and applies the resulting resources to the cluster using server-side apply.

One of the most powerful features of the Flux Kustomization is dependency ordering. You can specify that one Kustomization depends on another using the dependsOn field, creating a deployment order. For example, you might configure your infrastructure Kustomization (which deploys cert-manager and ingress-nginx) to be applied before your applications Kustomization (which deploys payments-api and order-service). The applications Kustomization will not start reconciling until the infrastructure Kustomization reports a healthy status. This eliminates the common problem of applications deploying before their dependencies are ready.

Health checking is another critical capability. When a Kustomization has health checks enabled, the controller does not consider a reconciliation successful until all deployed resources pass their health checks. For Deployments, this means all replicas are available. For StatefulSets, all pods must be ready. For custom resources, you can define custom health checks using status conditions. If health checks fail within the configured timeout, the Kustomization is marked as failed, and if retry is configured, the controller attempts reconciliation again. This prevents a broken deployment from being silently treated as successful.

The pruning feature (enabled with prune: true) implements garbage collection for GitOps. When a manifest is removed from Git, the Kustomization controller detects that the corresponding Kubernetes resource is no longer defined and deletes it from the cluster. Without pruning, removing a file from Git would leave orphaned resources running in the cluster. Pruning works by labeling all resources managed by a Kustomization with a unique identifier and periodically checking which labeled resources still have corresponding manifests. Resources that no longer have manifests are deleted. This is essential for maintaining the Git-equals-cluster invariant that GitOps promises, ensuring that the cluster state always matches what is defined in the repository.