GitOps mit ArgoCD: 5 Anti-Patterns, die Releases ausbremsen

GitOps verspricht reproduzierbare, auditierbare Deployments – Git als Single Source of Truth, ArgoCD als Ausführungsmotor. In der Praxis scheitern Teams jedoch regelmäßig nicht an der Technologie selbst, sondern an strukturellen Fehlern in der Art, wie sie ArgoCD einsetzen. Dieser Artikel beleuchtet fünf verbreitete Anti-Patterns, erklärt warum sie entstehen und zeigt konkrete Wege heraus.

1. Monorepo ohne App-of-Apps-Struktur

Viele Teams starten damit, alle Kubernetes-Manifeste in einem einzigen Git-Repository zu sammeln. Das klingt praktisch – alles an einem Ort – führt aber schnell dazu, dass ArgoCD bei jeder Änderung potenziell alle Applikationen neu synchronisiert. Ohne eine durchdachte Verzeichnisstruktur und ohne das App-of-Apps-Pattern entstehen monolithische ArgoCD-Applications, die Hunderte von Ressourcen auf einmal verwalten.

Das eigentliche Problem: Ein einziger fehlerhafter Commit im Monorepo kann Sync-Fehler in unzusammenhängenden Services auslösen. Außerdem verlieren Teams die Möglichkeit, granulare RBAC-Regeln auf Repository-Ebene durchzusetzen – jeder, der das Repo schreiben kann, kann alle Deployments beeinflussen.

Der Ausweg ist das App-of-Apps-Pattern: Eine übergeordnete ArgoCD-Application verwaltet ausschließlich andere Application-Objekte. Jede Teilapplikation verweist auf ein eigenes Unterverzeichnis oder ein separates Repository. Änderungen bleiben isoliert, Sync-Wellen werden vermieden.

2. Image-Versionen manuell im Git-Repo pflegen

Ein häufig unterschätztes Anti-Pattern: Entwickler pushen einen neuen Container-Image-Tag direkt per Hand in die Manifeste des GitOps-Repos. Das erfordert entweder manuelle Schritte nach jedem Build oder fragile CI-Skripte, die mit sed durch YAML-Dateien schreiben.

# Typisches CI-Skript-Antipattern
IMAGE_TAG=$(git rev-parse --short HEAD)
sed -i "s|image: myapp:.*|image: myapp:${IMAGE_TAG}|g" deploy/deployment.yaml
git add deploy/deployment.yaml
git commit -m "chore: update image to ${IMAGE_TAG}"
git push origin main

Dieses Muster erzeugt Rauschen in der Git-History, vermischt Build-Artefakte mit Konfigurationsänderungen und bricht regelmäßig bei parallelen Branches. Zudem entsteht eine enge Kopplung zwischen CI-Pipeline und GitOps-Repo – beides muss synchron gehalten werden.

Die sauberere Lösung ist der Einsatz von Argo CD Image Updater. Er überwacht Container-Registries auf neue Tags, aktualisiert die Manifeste automatisiert nach konfigurierbaren Strategien (semver, latest, digest) und commitet die Änderung selbst zurück in Git. Das CI-System baut und pushed das Image; der Rest ist Sache des Image Updaters.

3. Sync-Waves ignorieren und Ressourcen-Abhängigkeiten dem Zufall überlassen

ArgoCD synchronisiert Ressourcen standardmäßig parallel. Für einfache Deployments funktioniert das gut – bei komplexeren Stacks, die auf CRDs, Secrets oder Datenbankmigration angewiesen sind, führt es zu Race Conditions. Eine Applikation startet, bevor der zugehörige Secret aus dem externen Secret-Manager befüllt wurde; ein Operator läuft an, bevor seine CRD registriert ist.

Teams, die Sync-Waves ignorieren, kämpfen mit inkonsistenten Deployment-Ergebnissen: Mal funktioniert ein Rollout, mal nicht – abhängig davon, welche Ressource zufällig zuerst bereit war.

ArgoCD bietet mit der Annotation argocd.argoproj.io/sync-wave ein einfaches Mittel zur expliziten Reihenfolge. Niedrigere Werte werden zuerst angewendet und müssen healthy sein, bevor die nächste Wave beginnt. Ergänzend greifen Sync Hooks (PreSync, Sync, PostSync) für Jobs wie Datenbankmigrationen, die genau einmal und zum richtigen Zeitpunkt laufen müssen.

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
    argocd.argoproj.io/sync-wave: "-1"
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: myapp:1.4.2
          command: ["./migrate", "--run"]
      restartPolicy: Never

4. Auto-Sync ohne aussagekräftige Health Checks aktivieren

Auto-Sync klingt nach dem Versprechen von GitOps: Jede Änderung im Repository wird sofort im Cluster durchgesetzt. Ohne korrekt konfigurierte Health Checks wird Auto-Sync jedoch zum Risiko. ArgoCD bewertet standardmäßig eine Ressource als "Healthy", sobald sie in den Cluster geschrieben wurde – unabhängig davon, ob die Pods tatsächlich starten.

Das Ergebnis: ArgoCD meldet einen erfolgreichen Sync, während die neue Version in einem CrashLoopBackOff steckt. Im schlimmsten Fall folgt die nächste Auto-Sync-Welle, bevor das Problem bemerkt wird.

Kurzfristig hilft es, die Option Self-Heal nur für Nicht-Produktionsumgebungen zu aktivieren und in Produktion weiterhin auf manuelle Syncs oder genehmigungspflichtige Pipelines zu setzen. Mittelfristig sollten Teams eigene Health Checks für Custom Resources registrieren und Deployments so konfigurieren, dass ArgoCD auf den Rollout-Status wartet – nicht nur auf die API-Akzeptanz.

5. Secrets direkt in Git versionieren

Das offensichtlichste Anti-Pattern ist gleichzeitig das gefährlichste: Passwörter, API-Keys und TLS-Zertifikate landen als Base64-kodierte Kubernetes-Secrets im GitOps-Repository. Base64 ist keine Verschlüsselung. Wer Lesezugriff auf das Repo hat, kann alle Secrets extrahieren.

Dieser Fehler entsteht oft aus pragmatischem Druck – alles soll in Git liegen, auch Secrets, weil sonst "GitOps nicht vollständig" sei. Das Argument ist falsch. GitOps bedeutet, dass der gewünschte Zustand in Git liegt. Für Secrets bedeutet das: ein Verweis auf den Secret, nicht der Secret selbst.

Bewährte Alternativen:

• Sealed Secrets (Bitnami): Asymmetrische Verschlüsselung, nur der Controller im Cluster kann entschlüsseln. Der verschlüsselte Blob ist sicher in Git.
• External Secrets Operator: Kubernetes-Ressourcen verweisen auf externe Stores (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Der Operator materialisiert die Secrets zur Laufzeit im Cluster.
• Vault Agent Injector: Secrets werden direkt in Pods injiziert, ohne je in etcd oder Git zu landen.

Welche Lösung passt, hängt von der bestehenden Infrastruktur ab. Entscheidend ist: Kein Klartext und kein Base64 in Git – ohne Ausnahme.

6. Fehlende Environment Parity durch Copy-Paste-Manifeste

Wächst eine GitOps-Struktur organisch, entstehen häufig drei Verzeichnisse – dev/, staging/, prod/ – die irgendwann weitgehend identisch sind, aber jeweils leicht unterschiedlich von Hand gepflegt werden. Konfigurationsunterschiede zwischen Environments schleichen sich ein; ein Bugfix in einem Manifest wird vergessen in das andere zu übertragen.

Kustomize und Helm lösen dieses Problem strukturell. Mit Kustomize definiert eine base/-Schicht die gemeinsame Konfiguration; Overlays pro Environment überschreiben nur das, was sich tatsächlich unterscheidet (Replikanzahl, Resource Limits, Ingress-Hostname). ArgoCD unterstützt beide Werkzeuge nativ – kein Plugin erforderlich.

7. Keine Strategie für Drift Detection und Out-of-Band-Änderungen

GitOps setzt voraus, dass Git der einzige Weg ist, um den Cluster-Zustand zu verändern. In der Realität passiert es: Ein Administrator patcht einen Pod manuell mit kubectl edit, um einen kritischen Fehler schnell zu beheben. ArgoCD erkennt die Abweichung – und synchronisiert sie beim nächsten Sync zurück auf den Git-Stand.

Das Problem ist nicht die Technologie, sondern das fehlende Prozessverständnis. Teams brauchen klare Regeln: Out-of-Band-Änderungen sind verboten außer in deklarierten Notfallprozeduren, und auch Notfalländerungen müssen innerhalb von definierten Zeitfenstern in Git nachgezogen werden.

ArgoCD bietet mit dem Drift Detection-Dashboard und Webhooks die Infrastruktur, um Abweichungen sichtbar zu machen und Alerts auszulösen. Diese Sichtbarkeit nutzt nur, wer sie auch in Team-Prozesse einbettet – wer Alerts ignoriert, hat trotzdem Drift.

Fazit: GitOps ist kein Selbstläufer

ArgoCD ist ein mächtiges Werkzeug, das seine Stärken ausspielen kann – wenn die umgebenden Strukturen stimmen. Die beschriebenen Anti-Patterns entstehen selten aus Unwissenheit, häufiger aus dem Druck, schnell liefern zu müssen, ohne die Grundlagen sauber aufzusetzen. Das rächt sich regelmäßig: manuelle Eingriffe, inkonsistente Environments, Sicherheitsvorfälle durch exponierte Secrets.

Der Weg zu stabilen Releases führt über explizite Struktur (App-of-Apps, Kustomize-Overlays), automatisierte Hilfsmittel (Image Updater, External Secrets Operator) und klare Teamprozesse rund um Drift und Notfallprozeduren. Keiner dieser Schritte erfordert eine komplette Neuentwicklung – die meisten lassen sich inkrementell einführen, ohne laufende Deployments zu gefährden.