Eine Deployment-Revision durch FluxCD verfolgen

Wann dieses Runbook hilft

Ein Commit ist in Git angekommen, aber die erwartete Anwendungsversion läuft noch nicht. Drei Fragen getrennt beantworten: Hat Flux die Quelle abgerufen, den Sollzustand angewendet und sind die Ressourcen bereit geworden?

Meine Plattformarbeit bei jaraco nutzt FluxCD und GitHub Actions. Ich habe diese Notiz geschrieben, weil GitOps-Fehler schnell unklar wirken, wenn CI erfolgreich war, im Cluster aber trotzdem nicht die erwartete Version läuft. Die folgenden Befehle sind eine allgemeine Diagnoseanleitung auf Basis der öffentlichen Flux-Dokumentation, keine Kopie eines internen Runbooks.

1. Kontext bestätigen

kubectl config current-context
flux check
flux get all -A --status-selector ready=false

Zuerst den vorgesehenen Cluster bestätigen. flux check prüft Installation und Controller-Bereitschaft; der letzte Befehl grenzt die Untersuchung auf nicht bereite Ressourcen ein.

2. Quellrevision prüfen

flux get sources all -A
kubectl get gitrepositories.source.toolkit.fluxcd.io -A

Readiness, Suspend-Status und beobachtete Revision ansehen. Ist die Quelle nicht bereit, zuerst Zugriff, ausgewählten Branch oder Tag und Events des Source-Controllers untersuchen.

3. Anwendenden Controller prüfen

flux get kustomizations -A
flux get helmreleases -A
flux logs --all-namespaces --level=error
kubectl get events -n flux-system --field-selector type=Warning

Bei einer Kustomization Quelle, Pfad, Abhängigkeiten und Reconciliation-Meldung prüfen. Bei einem HelmRelease zusätzlich Chart-Quelle, Version sowie Installations- oder Upgrade-Ergebnis ansehen. Vollständig qualifizierte Ressourcennamen verhindern Verwechslungen bei mehreren Helm-Controllern.

4. Workload-Readiness untersuchen

Eine Quelle kann bereit sein, während die Anwendung es nicht ist. Image-Pull-Fehler, Scheduling-Einschränkungen, Speicher-Mounts oder Readiness-Prüfungen können den Rollout blockieren. Sobald die gewünschte Revision im Cluster angekommen ist, hilft das Runbook für blockierte Rollouts.

5. Über den Sollzustand wiederherstellen

Konfiguration in Git korrigieren oder die betreffende Änderung zurücknehmen. Anschließend beobachten, wie Quelle und anwendender Controller konvergieren. Nach der Ursachenbehebung kann ein Abgleich angefordert werden; wiederholtes Anstoßen ohne Änderung ersetzt keine Diagnose.

Die Untersuchung erst abschließen, wenn die gewünschte Revision sichtbar ist, die Ressourcen bereit sind und die Anwendungssignale einen gesunden Zustand zeigen. Es geht nicht darum, jede Abfrage mechanisch auszuführen, sondern Quelle, Controller, Workload und Nutzerwirkung in dieselbe Geschichte zu bringen.

Quelle

Flux Troubleshooting Cheatsheet, geprüft am 13. September 2026. Für konkretes Controller-Verhalten die Dokumentation der installierten Flux-Version verwenden.