# GitOps mit Argo CD: Automatisiertes Deployment in Kubernetes Argo CD ist ein deklaratives GitOps-Continuous-Delivery-Tool für Kubernetes, das den in einem Git-Repository definierten Sollzustand kontinuierlich mit dem tatsächlichen Cluster-Zustand abgleicht. Git dient dabei als Single Source of Truth. Abweichungen werden per Drift Detection erkannt und können durch Automated Sync und Self-Healing automatisch korrigiert werden. ## Das GitOps-Prinzip: Push vs. Pull Bei klassischen [Continuous-Delivery](https://www.ionos.de/digitalguide/websites/web-entwicklung/continuous-delivery/)-Pipelines kommt häufig ein Push-Modell zum Einsatz. Nachdem eine CI-Plattform beispielsweise ein neues Container-Image erstellt hat, führt sie selbst Befehle wie `kubectl apply` oder `helm upgrade` gegen den [Kubernetes-Cluster](https://www.ionos.de/digitalguide/server/knowhow/kubernetes-cluster/) aus. Die CI-Umgebung benötigt dafür Netzwerkzugriff auf die [Kubernetes](https://www.ionos.de/digitalguide/server/knowhow/was-ist-kubernetes/)-API sowie entsprechende Cluster-Zugangsdaten. [GitOps](https://www.ionos.de/digitalguide/websites/web-entwicklung/gitops/) verschiebt diese Verantwortung. Nach den OpenGitOps-Prinzipien soll der gewünschte Systemzustand **deklarativ vorliegen sowie versioniert und in unveränderlichen Versionen gespeichert werden**. Er wird automatisch aus seiner Quelle abgerufen und kontinuierlich mit dem tatsächlichen Zustand abgeglichen. Argo CD setzt dieses Prinzip über den [Repository](https://www.ionos.de/digitalguide/server/knowhow/repository/) Server und den Application Controller um. Der Repository Server **verarbeitet die konfigurierten Quellen und erzeugt daraus die Kubernetes-Manifeste**. Der Application Controller vergleicht diesen Sollzustand mit den Ressourcen im Kubernetes-Cluster. Erkennt er einen Unterschied, erhält die Anwendung den Status `OutOfSync`. Abhängig von der konfigurierten Sync Policy kann Argo CD die Änderung anschließend automatisch anwenden. Bei einer typischen Installation läuft Argo CD selbst innerhalb eines Kubernetes-Clusters. Eine zentrale Argo-CD-Instanz kann jedoch auch externe Kubernetes-Cluster verwalten. Das Pull-Prinzip bedeutet deshalb nicht zwingend, dass in jedem Ziel-Cluster ein eigener Agent installiert werden muss. Entscheidend ist, dass die **Deployment-Logik von Argo CD ausgeht** und die CI-Pipeline nicht direkt in den Ziel-Cluster deployen muss.
Merkmal Push-based CD Pull-based GitOps mit Argo CD
Deployment CI/CD-Pipeline pusht Änderungen in den Cluster Argo CD synchronisiert Git-Zustand und Cluster
Credentials CI/CD benötigt Cluster-Zugangsdaten Cluster-Credentials verbleiben bei Argo CD
Sicherheit CI/CD-System benötigt Zugriff auf die Kubernetes-API CI-Pipeline benötigt keinen direkten Cluster-Zugriff
Skalierbarkeit Mehr Cluster erhöhen den Verwaltungsaufwand der Pipeline Argo CD kann mehrere Anwendungen und Cluster verwalten
Drift-Management Zusätzliche Mechanismen erforderlich Abweichungen werden automatisch erkannt
Wiederherstellung Meist erneutes Deployment erforderlich Self-Heal kann den Git-Sollzustand wiederherstellen
Der Sicherheitsvorteil des Pull-Modells besteht somit vor allem darin, dass der CI-Server **nicht selbst weitreichende Zugriffsrechte** auf Produktionscluster benötigt. Zugangsdaten verschwinden dadurch allerdings nicht vollständig: Argo CD verwaltet Repository- und gegebenenfalls Cluster-Credentials selbst und speichert entsprechende Verbindungsinformationen als Kubernetes-Secrets. ## Argo CD installieren und einrichten Für die grundlegende Installation benötigen Sie einen erreichbaren Kubernetes-Cluster, `kubectl` sowie eine konfigurierte `kubeconfig`. Für die Arbeit mit der Kommandozeile können Sie zusätzlich die Argo-CD-CLI installieren. ### Schritt 1: Namespace für Argo CD erstellen Erstellen Sie zunächst einen separaten Namespace für die Argo-CD-Komponenten: ```bash kubectl create namespace argocd ``` argocd ist der Standard-Namespace für die Installation. Wenn Sie Argo CD in einem anderen Namespace installieren, müssen Sie die entsprechenden Namespace-Referenzen in den Installationsmanifesten anpassen. ### Schritt 2: Argo CD über Manifeste oder Helm installieren Für einen direkten Einstieg können Sie die offiziellen Installationsmanifeste verwenden. Für eine reproduzierbare Installation empfiehlt es sich, eine konkrete getestete Argo-CD-Version festzulegen: ```bash kubectl apply -n argocd \ --server-side \ --force-conflicts \ -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.3/manifests/install.yaml ``` Server-Side Apply wird unter anderem deshalb verwendet, weil einzelne Argo-CD-CRDs wie die ApplicationSet-CRD die Größenbeschränkung von 262 KB der bei Client-Side Apply verwendeten last-applied-configuration-Annotation überschreiten können. --force-conflicts ist bei Neuinstallationen unproblematisch, kann bei Upgrades jedoch eigene Anpassungen an Feldern überschreiben, die auch in den Argo-CD-Manifesten definiert sind. Prüfen Sie solche Anpassungen daher vor einem Upgrade. Hinweis Das obige Beispiel verwendet die Version v3.5.3. Zum Redaktionsstand ist v3.5.5 die aktuelle stabile Version von Argo CD. Da Argo CD regelmäßig neue Releases veröffentlicht, sollten Sie die Versionsnummer **vor der Installation prüfen und gegebenenfalls anpassen**. Die Standardinstallation ohne High Availability eignet sich vor allem **für Evaluationen, Tests und Demonstrationen** und wird von Argo CD nicht für den Produktivbetrieb empfohlen. Für produktive Installationen stehen unter manifests/ha/install.yaml HA-Manifeste bereit. Alternativ können Sie das von der Argo-Community gepflegte Helm-Chart verwenden: ```bash helm repo add argo https://argoproj.github.io/argo-helm helm repo update helm install argocd argo/argo-cd \ --namespace argocd ``` Das Helm-Chart bietet sich insbesondere dann an, wenn Sie die Installation **über eine eigene values.yaml konfigurieren** oder Argo CD selbst **deklarativ verwalten** möchten. Das Chart wird im argo-helm-Repository gepflegt und ist nicht Bestandteil der eigentlichen Argo-CD-Release-Manifeste. ### Schritt 3: API-Server und Weboberfläche erreichbar machen Der Dienst `argocd-server` ist nach der Standardinstallation **nicht automatisch** von außerhalb des Clusters erreichbar. Für einen lokalen Zugriff können Sie deshalb ein Port-Forwarding einrichten: ```bash kubectl port-forward svc/argocd-server \ -n argocd 8080:443 ``` Anschließend erreichen Sie die Weboberfläche unter https://localhost:8080. Für dauerhaft betriebene Installationen kann Argo CD stattdessen über einen Ingress oder einen [LoadBalancer](https://www.ionos.de/digitalguide/server/knowhow/bessere-serverzugriffszeiten-durch-load-balancer/)-Service veröffentlicht werden. Dabei sollten Sie insbesondere [TLS](https://www.ionos.de/digitalguide/server/sicherheit/tls-transport-layer-security/), Authentifizierung und den Zugriff auf die Verwaltungsoberfläche entsprechend Ihrer Cluster-Umgebung absichern. Zu den zentralen Komponenten gehören der [API](https://www.ionos.de/digitalguide/websites/web-entwicklung/was-ist-eine-api/) Server für Weboberfläche, CLI und API-Zugriffe, der Repository Server zur Verarbeitung der Git-Quellen und der Application Controller für den eigentlichen Reconciliation Loop. Der Controller vergleicht den gewünschten Zustand mit den laufenden Kubernetes-Ressourcen und führt bei entsprechender Konfiguration die Synchronisierung aus. ### Schritt 4: Anmelden und Git-Repository konfigurieren Für das initial angelegte `admin`-Konto erzeugt Argo CD ein temporäres Passwort. Dieses können Sie über die CLI abrufen: ```bash argocd admin initial-password -n argocd ``` Wenn Sie über das zuvor eingerichtete Port-Forwarding arbeiten, können Sie sich anschließend anmelden: ```bash argocd login localhost:8080 ``` Bei Verwendung des standardmäßig erzeugten selbstsignierten Zertifikats kann für eine lokale Testumgebung zusätzlich --insecure erforderlich sein. In einer produktiven Umgebung sollten Sie stattdessen eine **ordnungsgemäße TLS-Konfiguration** verwenden. Nach dem ersten Login sollten Sie das initiale Passwort ändern und ein eigenes [sicheres Passwort](https://www.ionos.de/digitalguide/server/sicherheit/sensible-daten-durch-ein-sicheres-passwort-schuetzen/) hinterlegen: ```bash argocd account update-password ``` Das Secret argocd-initial-admin-secret wird danach nicht mehr benötigt und kann entfernt werden. Öffentliche Git-Repositorys können ohne zusätzliche Zugangsdaten als Quelle verwendet werden. Für private Repositorys konfigurieren Sie beispielsweise ein HTTPS-Token oder einen [SSH](https://www.ionos.de/digitalguide/server/tools/secure-shell-ssh/)-Key. Eine HTTPS-Verbindung kann über die CLI folgendermaßen registriert werden: ```bash argocd repo add https://github.com/example/my-gitops-repo.git \ --username \ --password ``` Argo CD unterstützt für private Git-Repositorys unter anderem HTTPS-Zugangsdaten, Access Tokens, SSH-Schlüssel und verschiedene anbieterspezifische Authentifizierungsverfahren. Damit ist die Argo-CD-Installation bereit, Anwendungen anhand eines deklarativ definierten Repository-Zustands zu verwalten. ## Eine Argo-CD-Application definieren Das zentrale Konfigurationsobjekt für ein Deployment ist die **Custom Resource Definition** (CRD) `Application`. Eine `Application` beschreibt, wo Argo CD den gewünschten Zustand einer Anwendung findet und wohin dieser Zustand ausgerollt werden soll. Dabei verbindet die Ressource insbesondere **zwei Bereiche** miteinander. Unter `source` wird definiert, aus welchem Repository, welcher Revision und welchem Verzeichnis die Kubernetes-Konfiguration stammt. Unter `destination` wird festgelegt, in welchen Kubernetes-Cluster und Namespace Argo CD diese Ressourcen synchronisieren soll. Eine einfache `Application` kann beispielsweise wie folgt aussehen: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: example-app namespace: argocd spec: project: default source: repoURL: https://github.com/example/my-gitops-repo.git targetRevision: main path: kubernetes/production destination: server: https://kubernetes.default.svc namespace: example-app syncPolicy: automated: enabled: true prune: true selfHeal: true syncOptions: - CreateNamespace=true ``` Das Feld repoURL verweist in diesem Beispiel auf das Git-Repository. Mit targetRevision legen Sie die zu beobachtende Revision fest. Dabei kann es sich um einen Branch, ein Tag oder einen konkreten Commit handeln. path bezeichnet das Verzeichnis innerhalb des Repositorys, in dem sich die für diese Anwendung relevanten Ressourcen befinden. Der Eintrag server: https://kubernetes.default.svc legt den Kubernetes-Cluster fest, in dem Argo CD selbst ausgeführt wird. Argo CD kann zusätzlich externe Cluster registrieren und als Destination verwenden. ## Helm- und Kustomize-Integration Die Source einer `Application` muss **nicht ausschließlich** aus fertigen Kubernetes-YAML-Dateien bestehen. Argo CD verfügt über eine integrierte Unterstützung für Helm und Kustomize. Befindet sich im angegebenen Git-Pfad beispielsweise eine `kustomization.yaml`, kann Argo CD daraus die endgültigen Kubernetes-Manifeste erzeugen. Damit lassen sich **unterschiedliche Kustomize-Overlays** für Development-, Staging- und Production-Umgebungen in Git verwalten. Auch Helm-Charts können als Application-Source verwendet werden. Bei Helm übernimmt Argo CD die **Rendering-Funktion** und erzeugt über Helm Templates die Kubernetes-Manifeste. Den eigentlichen Lifecycle der Anwendung verwaltet anschließend Argo CD und nicht Helm selbst. Seit Argo CD 3.5 kommt ausschließlich Helm 4 zum Einsatz; eine vorhandene Einstellung `spec.source.helm.version: v3` wird ignoriert. Da der Wechsel das Rendering bestehender Charts beeinflussen kann und Breaking Changes unter anderem bei OCI-Repositorys über HTTP mit sich bringt, sollten bestehende Helm-Anwendungen vor einem Produktiv-Upgrade mit Helm 4 getestet werden. ## Drift Detection und Self-Healing Ein wesentlicher Unterschied zwischen einer einmal ausgeführten Deployment-Pipeline und GitOps besteht darin, dass die Arbeit **nach dem Deployment nicht beendet** ist. Argo CD führt den Reconciliation Loop fort und vergleicht den in Git gespeicherten Sollzustand regelmäßig mit dem Live-Zustand im Kubernetes-Cluster. Wird beispielsweise ein Deployment manuell verändert, entsteht sogenannter Configuration Drift. Wenn Git weiterhin drei Replikate definiert, ein Administrator im Cluster jedoch manuell fünf Replikate konfiguriert, unterscheiden sich Soll- und Istzustand. Argo CD erkennt die Anwendung in diesem Fall als `OutOfSync`. Ob Argo CD diese Abweichung lediglich meldet oder selbst korrigiert, wird über die Sync Policy gesteuert. Mit ```yaml syncPolicy: automated: enabled: true ``` aktivieren Sie **Automated Sync**. Dadurch kann Argo CD Änderungen aus der beobachteten Git-Revision automatisch auf den Cluster übertragen, sobald die Anwendung OutOfSync ist. Die CI-Pipeline muss in diesem Modell lediglich die deklarative Konfiguration in Git aktualisieren und benötigt keinen separaten Deployment-Aufruf an Argo CD oder Kubernetes. Für die automatische Korrektur manueller Änderungen am Live-Cluster muss zusätzlich Self-Healing aktiviert sein: ```yaml syncPolicy: automated: enabled: true selfHeal: true ``` Mit selfHeal: true kann Argo CD einen erneuten Sync auslösen, wenn sich der Cluster-Zustand verändert hat, obwohl sich die entsprechende Git-Revision nicht geändert hat. Dadurch wird beispielsweise eine manuelle Änderung am Deployment wieder auf den in Git festgelegten Wert zurückgeführt. Optional können Sie zusätzlich `prune` aktivieren: ```yaml syncPolicy: automated: enabled: true prune: true selfHeal: true ``` prune: true sorgt dafür, dass Argo CD zuvor verwaltete Ressourcen auch aus dem Cluster entfernt, wenn sie aus der gewünschten Konfiguration entfernt wurden. Da dies Löschoperationen automatisiert, sollte **diese Einstellung bewusst eingesetzt werden**. Argo CD stellt für besonders kritische Ressourcen zusätzliche Sync Options wie Prune=confirm bereit, mit denen eine Löschung **zunächst bestätigt** werden muss. Automated Sync und Self-Heal sind dabei **nicht** mit einem klassischen Rollback gleichzusetzen. Self-Healing stellt den aktuell in Git definierten Sollzustand wieder her. Ein Rollback bezeichnet dagegen den Wechsel auf eine frühere Revision. Argo CD behandelt Rollbacks als separaten Vorgang; für Anwendungen mit aktiviertem Automated Sync ist ein solcher Rollback nicht direkt verfügbar, solange die automatische Synchronisierung aktiv ist. Hinweis Argo CD prüft Git- und Helm-Repositorys standardmäßig in einem Intervall von 120 Sekunden zuzüglich eines zufälligen Jitters von bis zu 60 Sekunden auf Änderungen. Über Webhooks lassen sich Repository-Änderungen erkennen, ohne auf den nächsten Polling-Zyklus zu warten. Das Intervall und der Jitter können über timeout.reconciliation und timeout.reconciliation.jitter in der ConfigMap argocd-cm angepasst werden; mit timeout.reconciliation: 0 lässt sich das automatische Polling vollständig deaktivieren. ## Git als Single Source of Truth Der entscheidende organisatorische Schritt beim Einsatz von Argo CD besteht darin, Git tatsächlich als **Single Source of Truth** zu behandeln. Änderungen an Kubernetes-Ressourcen sollten deshalb nicht dauerhaft über manuelle `kubectl`-Befehle oder Änderungen in der Cluster-Oberfläche vorgenommen werden. Stattdessen wird die gewünschte Änderung in Git eingetragen, geprüft und versioniert. Der daraus resultierende Ablauf ist klar definiert: Eine Konfigurationsänderung wird zunächst in Git vorgenommen. Argo CD erkennt den neuen gewünschten Zustand, rendert gegebenenfalls Helm-Charts oder Kustomize-Konfigurationen und vergleicht das Ergebnis mit den vorhandenen Kubernetes-Ressourcen. Anschließend synchronisiert der Application Controller die notwendigen Änderungen mit dem Cluster. Durch den fortlaufenden Reconciliation Loop werden spätere Abweichungen erneut erkannt und können über Self-Healing automatisch korrigiert werden. Dadurch bleibt nicht nur dokumentiert, welcher Zustand aktuell im Cluster vorhanden sein soll. Über die Git-Historie ist ebenfalls nachvollziehbar, **wann** eine Konfiguration geändert wurde und **welche Version zuvor** verwendet wurde. Argo CD ergänzt diese versionierte Konfiguration um die kontinuierliche technische Kontrolle, ob der tatsächliche Kubernetes-Zustand weiterhin mit dieser Definition übereinstimmt. This is a markdown version of: [https://www.ionos.de/digitalguide/server/konfiguration/gitops-argocd-deployment-in-kubernetes/](https://www.ionos.de/digitalguide/server/konfiguration/gitops-argocd-deployment-in-kubernetes/) for AI/LLM consumption.