↓ Skip to main content
  1. Runbook/
  2. GitOps/

Flux Kustomization Troubleshooting

FluxCD Kustomize GitOps Kubernetes Troubleshooting

Time guide

  • Initial Kustomization checks: approximately 5 to 10 minutes
  • Build or dependency investigation: approximately 15 to 30 minutes
  • Render, dry-run and reconciliation validation: approximately 20 to 45 minutes

Purpose
#

Use this entry when a Flux Kustomization is not ready, reports a build failure, waits on a dependency, or applies an unexpected revision.

Inspect status
#

flux get kustomization <kustomization-name> \
  -n <namespace>
kubectl describe kustomization <kustomization-name> \
  -n <namespace>
kubectl get kustomization <kustomization-name> \
  -n <namespace> \
  -o custom-columns='NAME:.metadata.name,PATH:.spec.path,SOURCE:.spec.sourceRef.name,PRUNE:.spec.prune,SUSPENDED:.spec.suspend,REVISION:.status.lastAppliedRevision'

Readiness message
#

kubectl get kustomization <kustomization-name> \
  -n <namespace> \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}{.status.conditions[?(@.type=="Ready")].reason}{"\n"}{.status.conditions[?(@.type=="Ready")].message}{"\n"}'

Source health
#

kubectl get kustomization <kustomization-name> \
  -n <namespace> \
  -o jsonpath='{.spec.sourceRef.kind}{"/"}{.spec.sourceRef.name}{"\n"}'
flux get sources all -A

Dependencies
#

kubectl get kustomization <kustomization-name> \
  -n <namespace> \
  -o jsonpath='{.spec.dependsOn}{"\n"}'
flux get kustomizations -A

Investigate any dependency that is not ready before reconciling the dependent object.

Local render
#

From the repository root:

kubectl kustomize <path-to-kustomization> \
  > /tmp/<kustomization-name>-rendered.yaml
test -s /tmp/<kustomization-name>-rendered.yaml
grep '^kind:' /tmp/<kustomization-name>-rendered.yaml

Dry runs
#

kubectl apply \
  --dry-run=client \
  -f /tmp/<kustomization-name>-rendered.yaml

After confirming context and permissions:

kubectl apply \
  --server-side \
  --dry-run=server \
  -f /tmp/<kustomization-name>-rendered.yaml

Controller logs and events
#

flux events \
  --for Kustomization/<kustomization-name> \
  -n <namespace>
kubectl logs \
  -n flux-system \
  deployment/kustomize-controller \
  --since=30m

Common reasons
#

BuildFailed
#

Check for:

  • Missing resource paths
  • Invalid YAML
  • Duplicate resources
  • Invalid patches
  • Unsupported API versions
  • SOPS decryption failures
  • Missing Helm chart inputs

DependencyNotReady
#

Inspect spec.dependsOn and the readiness of each dependency.

HealthCheckFailed
#

Check the target workloads:

kubectl get deployments,statefulsets,daemonsets -n <workload-namespace>
kubectl get pods -n <workload-namespace>
kubectl get events -n <workload-namespace> --sort-by=.metadata.creationTimestamp

Reconcile after validation
#

This can create, update or prune resources according to Git.

flux reconcile kustomization <kustomization-name> \
  -n <namespace> \
  --with-source

Post-reconciliation validation
#

flux get kustomization <kustomization-name> -n <namespace>
kubectl get kustomization <kustomization-name> \
  -n <namespace> \
  -o jsonpath='{.status.lastAppliedRevision}{"\n"}'
kubectl get pods -n <workload-namespace>
kubectl get events -n <workload-namespace> --sort-by=.metadata.creationTimestamp

Remove the temporary render:

rm /tmp/<kustomization-name>-rendered.yaml

Safety notes
#

A Kustomization with pruning enabled may delete resources absent from the desired state. Always review the rendered output, Git diff, cluster context and target path before manual reconciliation.

Related entries#

  • Flux Reconciliation Commands
  • Flux Controller Health Checks
  • GitOps Repository Structure
  • SOPS and age Secret Workflow
  • Kubernetes Pod and Workload Troubleshooting