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

Flux Controller Health Checks

FluxCD GitOps Kubernetes Controllers Troubleshooting

Time guide

  • Basic controller health check: approximately 5 to 10 minutes
  • Source or reconciliation investigation: approximately 15 to 30 minutes

Purpose
#

Use this entry when Flux resources are not reconciling, a source is stale, or one of the controllers appears unhealthy.

Installation checks
#

flux version
flux check

Controller workloads
#

kubectl get deployments -n flux-system
kubectl get pods -n flux-system -o wide
kubectl get deployments -n flux-system \
  -o custom-columns='NAME:.metadata.name,READY:.status.readyReplicas,AVAILABLE:.status.availableReplicas,DESIRED:.spec.replicas'

Flux resource health
#

flux get all -A
flux get sources all -A
flux get kustomizations -A
flux get helmreleases -A

Suspended resources
#

kubectl get kustomizations.kustomize.toolkit.fluxcd.io -A \
  -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SUSPENDED:.spec.suspend'
kubectl get gitrepositories.source.toolkit.fluxcd.io -A \
  -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SUSPENDED:.spec.suspend'

Events
#

flux events -A
kubectl get events -n flux-system \
  --sort-by=.metadata.creationTimestamp
kubectl get events -n flux-system \
  --field-selector=type=Warning \
  --sort-by=.metadata.creationTimestamp

Controller logs
#

kubectl logs -n flux-system deployment/source-controller --tail=200
kubectl logs -n flux-system deployment/kustomize-controller --tail=200
kubectl logs -n flux-system deployment/helm-controller --tail=200
kubectl logs -n flux-system deployment/notification-controller --tail=200

Search recent errors:

kubectl logs -n flux-system deployment/kustomize-controller --since=30m \
  | grep -iE 'error|failed|timeout'

Common findings
#

  • Authentication or repository access failure
  • Invalid source reference
  • Stale or unavailable source artifact
  • Kustomize build failure
  • SOPS decryption failure
  • Dependency not ready
  • Helm install or upgrade failure
  • Admission-policy rejection
  • Unhealthy target workload

Safety notes
#

All commands in this entry are read-only. Use the separate Flux Reconciliation entry only after confirming the cluster context, intended source revision and likely fault domain.

Related entries#

  • Flux Reconciliation Commands
  • GitRepository Troubleshooting
  • Kustomization Troubleshooting
  • HelmRelease Troubleshooting
  • SOPS and age Secret Workflow