ArgoCD GitOps für Kubernetes-Deployments

ArgoCD ist ein deklaratives, GitOps-basiertes Werkzeug für Continuous Delivery in Kubernetes, das den Clusterzustand dauerhaft mit den in Git gespeicherten Konfigurationen synchron hält. Wenn Sie je Zeit damit verbracht haben, nach jedem Code-Commit manuell kubectl apply auszuführen oder Konfigurationsabweichungen zwischen Umgebungen zu verfolgen, löst ArgoCD dieses Problem, indem Git zur einzigen Quelle der Wahrheit für jede bereitgestellte Ressource wird. Diese Anleitung führt Sie durch die Installation von ArgoCD, die Verbindung von Repositories, die Erstellung von Application-Ressourcen und die Konfiguration von Sync-Richtlinien für produktionstaugliche Deployments.

Voraussetzungen

• Ein laufender Kubernetes-Cluster (v1.22+) mit konfiguriertem kubectl
• Cluster-Admin-Berechtigungen zum Erstellen von Namespaces und CRDs
• Ein Git-Repository mit Kubernetes-Manifesten, Helm-Charts oder Kustomize-Overlays
• ArgoCD CLI (argocd) lokal installiert (optional, aber empfohlen)
• Grundkenntnisse von Kubernetes Deployments, Services und Namespaces

Was ist GitOps und warum ArgoCD?

GitOps ist ein Betriebsmodell, bei dem der gewünschte Zustand von Infrastruktur und Anwendungen in Git deklariert wird. Ein im Cluster laufender Operator vergleicht kontinuierlich den Ist-Zustand mit dem Soll-Zustand und gleicht Unterschiede ab. ArgoCD ist der am weitesten verbreitete Kubernetes-native GitOps-Operator mit CNCF-Graduated-Projektstatus seit 2022.

Die wichtigsten Vorteile gegenüber traditionellen push-basierten CI/CD-Pipelines:

Merkmal	ArgoCD (GitOps pull)	Jenkins / GitLab CI (push)
Speicherung von Zugangsdaten	Nur im Cluster	Im CI-System-Secret
Drift-Erkennung	Kontinuierlich, automatisch	Nur beim Deployment
Rollback-Mechanismus	Git-Revert auf jeden Commit	Alte Pipeline erneut ausführen
Audit-Protokoll	Git-Historie	CI-Logs
Multi-Cluster-Unterstützung	Nativ, pro Application	Manuelle Pipeline-Konfiguration
Self-Healing	Integrierte Sync-Schleife	Nicht verfügbar

Das Pull-Modell ist eine erhebliche Sicherheitsverbesserung: Ihre CI-Pipeline benötigt keine Cluster-Zugangsdaten mehr. ArgoCD läuft im Cluster und zieht Änderungen aus Git, immer nur ausgehend.

ArgoCD installieren

Erstellen Sie den dedizierten Namespace und wenden Sie das offizielle Installationsmanifest an:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Warten Sie, bis alle Pods den Zustand Running erreicht haben:

kubectl wait --for=condition=available deployment --all -n argocd --timeout=120s
kubectl get pods -n argocd

Auf die Weboberfläche zugreifen

Standardmäßig ist der argocd-server-Dienst vom Typ ClusterIP. Für lokalen Zugriff nutzen Sie Port-Forwarding:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Rufen Sie das automatisch generierte Admin-Passwort ab:

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath="{.data.password}" | base64 -d && echo

Melden Sie sich per CLI an:

argocd login localhost:8080 --username admin --password <passwort> --insecure

Für den Produktiveinsatz konfigurieren Sie einen Ingress mit TLS und integrieren Sie SSO (Dex mit GitHub/OIDC) statt des Admin-Kontos.

Ein Git-Repository verbinden

ArgoCD benötigt Zugriff auf Ihr Git-Repository, um Manifeste abzurufen. Bei öffentlichen Repos sind keine Zugangsdaten erforderlich. Für private Repositories:

argocd repo add https://github.com/ihre-org/ihr-k8s-repo \
  --username git \
  --password <token>

Für SSH:

argocd repo add git@github.com:ihre-org/ihr-k8s-repo.git \
  --ssh-private-key-path ~/.ssh/id_rsa

Sie können Repositories auch deklarativ als Kubernetes-Secrets mit dem Label argocd.argoproj.io/secret-type: repository verwalten, wenn Sie eine vollständige GitOps-Verwaltung von ArgoCD selbst bevorzugen.

ArgoCD-Applications erstellen

Eine Application ist die zentrale ArgoCD-Ressource. Sie definiert was bereitgestellt wird, woher und in welchem Cluster und Namespace.

Deklaratives Application-Manifest

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: meine-web-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/ihre-org/ihr-k8s-repo
    targetRevision: main
    path: manifests/meine-web-app
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true

Anwenden:

kubectl apply -f meine-web-app-application.yaml

Applications mit Helm

ArgoCD unterstützt Helm nativ, ohne dass Helm auf CI-Systemen installiert sein muss:

source:
  repoURL: https://github.com/ihre-org/ihr-k8s-repo
  targetRevision: main
  path: charts/meine-web-app
  helm:
    valueFiles:
      - values-production.yaml
    parameters:
      - name: image.tag
        value: "v1.4.2"

Applications mit Kustomize

source:
  repoURL: https://github.com/ihre-org/ihr-k8s-repo
  targetRevision: main
  path: kustomize/overlays/production

ArgoCD erkennt kustomization.yaml automatisch und führt kustomize build transparent aus.

Sync-Richtlinien und Self-Healing

Die Sync-Richtlinie ist die wichtigste Konfigurationsentscheidung in ArgoCD.

Manueller Sync — ArgoCD erkennt Drift, erfordert aber eine Person (oder einen CI-Schritt), um die Synchronisation auszulösen. Nützlich für Produktionsumgebungen, in denen eine explizite Genehmigung vor dem Deployment gewünscht ist.

Automatischer Sync — ArgoCD synchronisiert automatisch, wenn Unterschiede zwischen Git und Cluster festgestellt werden. Kombinieren Sie dies mit Self-Healing und Pruning für vollständige Automatisierung:

syncPolicy:
  automated:
    selfHeal: true   # setzt manuelle kubectl-Änderungen zurück
    prune: true      # löscht aus Git entfernte Ressourcen
  retry:
    limit: 5
    backoff:
      duration: 5s
      maxDuration: 3m
      factor: 2

selfHeal: true bedeutet, dass ArgoCD eine Ressource innerhalb von Sekunden zurücksetzt, wenn jemand sie manuell mit kubectl ändert. Dies erzwingt strikte GitOps-Disziplin.

prune: true bedeutet, dass im Git-Repository gelöschte Ressourcen auch im Cluster gelöscht werden. Ohne Pruning häufen sich verwaiste Ressourcen mit der Zeit an.

Praxisszenario: Multi-Umgebungs-Promotion

Sie haben drei Umgebungen — dev, staging und production — jede in einem separaten Namespace mit umgebungsspezifischen Kustomize-Overlays. Ihre CI-Pipeline baut und pusht ein Docker-Image, aktualisiert dann den Image-Tag in der Datei dev/kustomization.yaml und committet in Git.

repo/
  kustomize/
    base/           ← gemeinsame Manifeste
    overlays/
      dev/          ← ArgoCD-App für dev-Namespace
      staging/      ← ArgoCD-App für staging-Namespace
      production/   ← ArgoCD-App für production-Namespace (manueller Sync)

ArgoCD für dev hat automated: {} (automatisches Deployment bei jedem Commit). ArgoCD für staging und production verwendet manuellen Sync — ein Ingenieur prüft den Diff in der UI und klickt auf Synchronisieren, oder eine PR-Genehmigung löst einen argocd app sync-CLI-Aufruf in der CI-Pipeline aus.

Dieses Muster hält die Promotion kontrolliert und über die Git-Historie nachvollziehbar, nicht über Jenkins-Build-Logs.

Stolperfallen und Sonderfälle

CRD-Reihenfolgeprobleme — Wenn Ihre App Custom Resource Definitions zusammen mit Ressourcen installiert, die diese verwenden, kann ArgoCD beim ersten Sync fehlschlagen, weil die CRDs noch nicht verfügbar sind. Verwenden Sie Sync Waves mit argocd.argoproj.io/sync-wave: "-1" auf CRD-Manifesten, damit diese zuerst angewendet werden.

Pruning und Jobs — ArgoCD-Pruning löscht abgeschlossene Jobs und deren Pods, wenn sie aus Git entfernt werden. Verwenden Sie argocd.argoproj.io/hook: PostSync und argocd.argoproj.io/hook-delete-policy: HookSucceeded für einmalige Migrations-Jobs.

Image-Tag-Strategie — Vermeiden Sie latest als Tag. ArgoCD vergleicht Manifeste, nicht Image-Digests, sodass ein neuer Push auf latest keinen Sync auslöst. Verwenden Sie unveränderliche Tags (Git-SHA oder Semver). Das ArgoCD Image Updater-Projekt kann Tag-Updates in Git automatisieren.

RBAC und Projects — Das default-Projekt erlaubt alle Repositories und Cluster. Für Multi-Team-Setups erstellen Sie AppProjects mit eingeschränktem Umfang für Quell-Repositories, Ziel-Namespaces und erlaubte Ressourcentypen.

Secret-Verwaltung — Speichern Sie niemals Kubernetes-Secret-Manifeste mit Klartext-Daten in Git. Verwenden Sie Sealed Secrets, External Secrets Operator oder mit SOPS verschlüsselte Secrets in Git.

Sync-Timeout — Lang laufende Helm-Hooks können den Standard-Sync-Timeout (300s) überschreiten. Erhöhen Sie ihn mit --timeout in der CLI oder konfigurieren Sie timeout.reconciliation in der ConfigMap argocd-cm.

Häufige Probleme

App steckt in Progressing — Prüfen Sie die Ausgabe von argocd app get <name> auf degradierte Ressourcen. Meist ein fehlgeschlagenes Deployment-Rollout oder ein ausstehender PVC. Führen Sie kubectl describe pod -n <namespace> am betroffenen Pod aus.

ComparisonError oder Unknown-Gesundheitsstatus — ArgoCD kann keine Manifeste abrufen. Prüfen Sie die Repository-Konnektivität mit argocd repo list und die Zugangsdaten.

Self-Healing-Schleife — Wenn ArgoCD eine Ressource wiederholt zurücksetzt, modifiziert ein Validierungs-Webhook oder Operator die Ressource nach der Anwendung durch ArgoCD. Verwenden Sie ignoreDifferences in der Application-Spec, um bestimmte Felder zu ignorieren.

Pruning löscht unerwartete Ressourcen — Stellen Sie sicher, dass alle von ArgoCD verwalteten Ressourcen das korrekte Label app.kubernetes.io/instance haben.

Zusammenfassung

• ArgoCD implementiert GitOps durch kontinuierliche Abstimmung des Clusterzustands mit dem in Git definierten Sollzustand
• Installation mit einem einzigen kubectl apply im argocd-Namespace; Zugriff per Port-Forwarding oder Ingress
• Applications werden deklarativ definiert und unterstützen rohe Manifeste, Helm-Charts und Kustomize
• Nutzen Sie automatischen Sync mit selfHeal und prune für Dev/Staging; manuellen Sync für Produktionsgenehmigungen
• Organisieren Sie Multi-Umgebungs-Setups mit Kustomize-Overlays oder Helm-Value-Dateien pro Umgebung
• Schützen Sie Secrets mit Sealed Secrets oder External Secrets Operator — niemals Klartext in Git
• Nutzen Sie Sync Waves für CRD-Reihenfolge und ArgoCD Image Updater für automatisierte Tag-Promotion
• RBAC-Projects begrenzen Repository- und Cluster-Zugriff in Multi-Team-Deployments

Verwandte Artikel

• Git: Fortgeschrittene Workflows mit Rebase, Bisect und Hooks
• GitLab CI/CD Pipeline-Konfigurationsleitfaden
• Kubernetes-Secret-Verwaltung mit SOPS und age
• Erste Schritte mit GitHub Actions CI/CD
• Kubernetes Pod-Fehlerbehebungsanleitung