GitOps mit Argo CD: Au­to­ma­ti­sier­tes De­ploy­ment in Ku­ber­netes

Argo CD ist ein de­kla­ra­ti­ves GitOps-Con­ti­nuous-Delivery-Tool für Ku­ber­netes, das den in einem Git-Re­po­si­to­ry de­fi­nier­ten Soll­zu­stand kon­ti­nu­ier­lich mit dem tat­säch­li­chen Cluster-Zustand abgleicht. Git dient dabei als Single Source of Truth. Ab­wei­chun­gen werden per Drift Detection erkannt und können durch Automated Sync und Self-Healing au­to­ma­tisch kor­ri­giert werden.

Das GitOps-Prinzip: Push vs. Pull

Bei klas­si­schen Con­ti­nuous-Delivery-Pipelines kommt häufig ein Push-Modell zum Einsatz. Nachdem eine CI-Plattform bei­spiels­wei­se ein neues Container-Image erstellt hat, führt sie selbst Befehle wie kubectl apply oder helm upgrade gegen den Ku­ber­netes-Cluster aus. Die CI-Umgebung benötigt dafür Netz­werk­zu­griff auf die Ku­ber­netes-API sowie ent­spre­chen­de Cluster-Zu­gangs­da­ten.

GitOps ver­schiebt diese Ver­ant­wor­tung. Nach den Open­Gi­tOps-Prin­zi­pi­en soll der ge­wünsch­te Sys­tem­zu­stand de­kla­ra­tiv vorliegen sowie ver­sio­niert und in un­ver­än­der­li­chen Versionen ge­spei­chert werden. Er wird au­to­ma­tisch aus seiner Quelle abgerufen und kon­ti­nu­ier­lich mit dem tat­säch­li­chen Zustand ab­ge­gli­chen.

Argo CD setzt dieses Prinzip über den Re­po­si­to­ry Server und den Ap­pli­ca­ti­on Con­trol­ler um. Der Re­po­si­to­ry Server ver­ar­bei­tet die kon­fi­gu­rier­ten Quellen und erzeugt daraus die Ku­ber­netes-Manifeste. Der Ap­pli­ca­ti­on Con­trol­ler ver­gleicht diesen Soll­zu­stand mit den Res­sour­cen im Ku­ber­netes-Cluster. Erkennt er einen Un­ter­schied, erhält die Anwendung den Status OutOfSync. Abhängig von der kon­fi­gu­rier­ten Sync Policy kann Argo CD die Änderung an­schlie­ßend au­to­ma­tisch anwenden.

Bei einer typischen In­stal­la­ti­on läuft Argo CD selbst innerhalb eines Ku­ber­netes-Clusters. Eine zentrale Argo-CD-Instanz kann jedoch auch externe Ku­ber­netes-Cluster verwalten. Das Pull-Prinzip bedeutet deshalb nicht zwingend, dass in jedem Ziel-Cluster ein eigener Agent in­stal­liert werden muss. Ent­schei­dend ist, dass die De­ploy­ment-Logik von Argo CD ausgeht und die CI-Pipeline nicht direkt in den Ziel-Cluster deployen muss.

Der Si­cher­heits­vor­teil des Pull-Modells besteht somit vor allem darin, dass der CI-Server nicht selbst weit­rei­chen­de Zu­griffs­rech­te auf Pro­duk­ti­ons­clus­ter benötigt. Zu­gangs­da­ten ver­schwin­den dadurch al­ler­dings nicht voll­stän­dig: Argo CD verwaltet Re­po­si­to­ry- und ge­ge­be­nen­falls Cluster-Cre­den­ti­als selbst und speichert ent­spre­chen­de Ver­bin­dungs­in­for­ma­tio­nen als Ku­ber­netes-Secrets.

Argo CD in­stal­lie­ren und ein­rich­ten

Für die grund­le­gen­de In­stal­la­ti­on benötigen Sie einen er­reich­ba­ren Ku­ber­netes-Cluster, kubectl sowie eine kon­fi­gu­rier­te kubeconfig. Für die Arbeit mit der Kom­man­do­zei­le können Sie zu­sätz­lich die Argo-CD-CLI in­stal­lie­ren.

Schritt 1: Namespace für Argo CD erstellen

Erstellen Sie zunächst einen separaten Namespace für die Argo-CD-Kom­po­nen­ten:

kubectl create namespace argocd

argocd ist der Standard-Namespace für die In­stal­la­ti­on. Wenn Sie Argo CD in einem anderen Namespace in­stal­lie­ren, müssen Sie die ent­spre­chen­den Namespace-Re­fe­ren­zen in den In­stal­la­ti­ons­ma­ni­fes­ten anpassen.

Schritt 2: Argo CD über Manifeste oder Helm in­stal­lie­ren

Für einen direkten Einstieg können Sie die of­fi­zi­el­len In­stal­la­ti­ons­ma­ni­fes­te verwenden. Für eine re­pro­du­zier­ba­re In­stal­la­ti­on empfiehlt es sich, eine konkrete getestete Argo-CD-Version fest­zu­le­gen:

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 Ap­pli­ca­ti­onS­et-CRD die Grö­ßen­be­schrän­kung von 262 KB der bei Client-Side Apply ver­wen­de­ten last-applied-configuration-An­no­ta­ti­on über­schrei­ten können. --force-conflicts ist bei Neu­in­stal­la­tio­nen un­pro­ble­ma­tisch, kann bei Upgrades jedoch eigene An­pas­sun­gen an Feldern über­schrei­ben, die auch in den Argo-CD-Ma­ni­fes­ten definiert sind. Prüfen Sie solche An­pas­sun­gen daher vor einem Upgrade.

Die Stan­dard­in­stal­la­ti­on ohne High Avai­la­bi­li­ty eignet sich vor allem für Eva­lua­tio­nen, Tests und De­mons­tra­tio­nen und wird von Argo CD nicht für den Pro­duk­tiv­be­trieb empfohlen. Für pro­duk­ti­ve In­stal­la­tio­nen stehen unter manifests/ha/install.yaml HA-Manifeste bereit.

Al­ter­na­tiv können Sie das von der Argo-Community gepflegte Helm-Chart verwenden:

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 ins­be­son­de­re dann an, wenn Sie die In­stal­la­ti­on über eine eigene values.yaml kon­fi­gu­rie­ren oder Argo CD selbst de­kla­ra­tiv verwalten möchten. Das Chart wird im argo-helm-Re­po­si­to­ry gepflegt und ist nicht Be­stand­teil der ei­gent­li­chen Argo-CD-Release-Manifeste.

Schritt 3: API-Server und Web­ober­flä­che er­reich­bar machen

Der Dienst argocd-server ist nach der Stan­dard­in­stal­la­ti­on nicht au­to­ma­tisch von außerhalb des Clusters er­reich­bar. Für einen lokalen Zugriff können Sie deshalb ein Port-For­war­ding ein­rich­ten:

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

An­schlie­ßend erreichen Sie die Web­ober­flä­che unter https://localhost:8080.

Für dauerhaft be­trie­be­ne In­stal­la­tio­nen kann Argo CD statt­des­sen über einen Ingress oder einen Load­Ba­lan­cer-Service ver­öf­fent­licht werden. Dabei sollten Sie ins­be­son­de­re TLS, Au­then­ti­fi­zie­rung und den Zugriff auf die Ver­wal­tungs­ober­flä­che ent­spre­chend Ihrer Cluster-Umgebung absichern.

Zu den zentralen Kom­po­nen­ten gehören der API Server für Web­ober­flä­che, CLI und API-Zugriffe, der Re­po­si­to­ry Server zur Ver­ar­bei­tung der Git-Quellen und der Ap­pli­ca­ti­on Con­trol­ler für den ei­gent­li­chen Re­con­ci­lia­ti­on Loop. Der Con­trol­ler ver­gleicht den ge­wünsch­ten Zustand mit den laufenden Ku­ber­netes-Res­sour­cen und führt bei ent­spre­chen­der Kon­fi­gu­ra­ti­on die Syn­chro­ni­sie­rung aus.

Schritt 4: Anmelden und Git-Re­po­si­to­ry kon­fi­gu­rie­ren

Für das initial angelegte admin-Konto erzeugt Argo CD ein tem­po­rä­res Passwort. Dieses können Sie über die CLI abrufen:

argocd admin initial-password -n argocd

Wenn Sie über das zuvor ein­ge­rich­te­te Port-For­war­ding arbeiten, können Sie sich an­schlie­ßend anmelden:

argocd login localhost:8080

Bei Ver­wen­dung des stan­dard­mä­ßig erzeugten selbst­si­gnier­ten Zer­ti­fi­kats kann für eine lokale Test­um­ge­bung zu­sätz­lich --insecure er­for­der­lich sein. In einer pro­duk­ti­ven Umgebung sollten Sie statt­des­sen eine ord­nungs­ge­mä­ße TLS-Kon­fi­gu­ra­ti­on verwenden.

Nach dem ersten Login sollten Sie das initiale Passwort ändern und ein eigenes sicheres Passwort hin­ter­le­gen:

argocd account update-password

Das Secret argocd-initial-admin-secret wird danach nicht mehr benötigt und kann entfernt werden.

Öf­fent­li­che Git-Re­po­si­to­rys können ohne zu­sätz­li­che Zu­gangs­da­ten als Quelle verwendet werden. Für private Re­po­si­to­rys kon­fi­gu­rie­ren Sie bei­spiels­wei­se ein HTTPS-Token oder einen SSH-Key. Eine HTTPS-Ver­bin­dung kann über die CLI fol­gen­der­ma­ßen re­gis­triert werden:

argocd repo add https://github.com/example/my-gitops-repo.git \
    --username <BENUTZERNAME> \
    --password <ACCESS_TOKEN>

Argo CD un­ter­stützt für private Git-Re­po­si­to­rys unter anderem HTTPS-Zu­gangs­da­ten, Access Tokens, SSH-Schlüssel und ver­schie­de­ne an­bie­ter­spe­zi­fi­sche Au­then­ti­fi­zie­rungs­ver­fah­ren. Damit ist die Argo-CD-In­stal­la­ti­on bereit, An­wen­dun­gen anhand eines de­kla­ra­tiv de­fi­nier­ten Re­po­si­to­ry-Zustands zu verwalten.

Eine Argo-CD-Ap­pli­ca­ti­on de­fi­nie­ren

Das zentrale Kon­fi­gu­ra­ti­ons­ob­jekt für ein De­ploy­ment ist die Custom Resource De­fi­ni­ti­on (CRD) Application. Eine Application be­schreibt, wo Argo CD den ge­wünsch­ten Zustand einer Anwendung findet und wohin dieser Zustand aus­ge­rollt werden soll.

Dabei verbindet die Ressource ins­be­son­de­re zwei Bereiche mit­ein­an­der. Unter source wird definiert, aus welchem Re­po­si­to­ry, welcher Revision und welchem Ver­zeich­nis die Ku­ber­netes-Kon­fi­gu­ra­ti­on stammt. Unter destination wird fest­ge­legt, in welchen Ku­ber­netes-Cluster und Namespace Argo CD diese Res­sour­cen syn­chro­ni­sie­ren soll.

Eine einfache Application kann bei­spiels­wei­se wie folgt aussehen:

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-Re­po­si­to­ry. Mit targetRevision legen Sie die zu be­ob­ach­ten­de Revision fest. Dabei kann es sich um einen Branch, ein Tag oder einen konkreten Commit handeln. path be­zeich­net das Ver­zeich­nis innerhalb des Re­po­si­to­rys, in dem sich die für diese Anwendung re­le­van­ten Res­sour­cen befinden. Der Eintrag server: https://kubernetes.default.svc legt den Ku­ber­netes-Cluster fest, in dem Argo CD selbst aus­ge­führt wird. Argo CD kann zu­sätz­lich externe Cluster re­gis­trie­ren und als De­sti­na­ti­on verwenden.

Helm- und Kustomize-In­te­gra­ti­on

Die Source einer Application muss nicht aus­schließ­lich aus fertigen Ku­ber­netes-YAML-Dateien bestehen. Argo CD verfügt über eine in­te­grier­te Un­ter­stüt­zung für Helm und Kustomize. Befindet sich im an­ge­ge­be­nen Git-Pfad bei­spiels­wei­se eine kustomization.yaml, kann Argo CD daraus die end­gül­ti­gen Ku­ber­netes-Manifeste erzeugen. Damit lassen sich un­ter­schied­li­che Kustomize-Overlays für De­ve­lo­p­ment-, Staging- und Pro­duc­tion-Um­ge­bun­gen in Git verwalten.

Auch Helm-Charts können als Ap­pli­ca­ti­on-Source verwendet werden. Bei Helm übernimmt Argo CD die Rendering-Funktion und erzeugt über Helm Templates die Ku­ber­netes-Manifeste. Den ei­gent­li­chen Lifecycle der Anwendung verwaltet an­schlie­ßend Argo CD und nicht Helm selbst. Seit Argo CD 3.5 kommt aus­schließ­lich Helm 4 zum Einsatz; eine vor­han­de­ne Ein­stel­lung spec.source.helm.version: v3 wird ignoriert. Da der Wechsel das Rendering be­stehen­der Charts be­ein­flus­sen kann und Breaking Changes unter anderem bei OCI-Re­po­si­to­rys über HTTP mit sich bringt, sollten be­stehen­de Helm-An­wen­dun­gen vor einem Produktiv-Upgrade mit Helm 4 getestet werden.

Drift Detection und Self-Healing

Ein we­sent­li­cher Un­ter­schied zwischen einer einmal aus­ge­führ­ten De­ploy­ment-Pipeline und GitOps besteht darin, dass die Arbeit nach dem De­ploy­ment nicht beendet ist. Argo CD führt den Re­con­ci­lia­ti­on Loop fort und ver­gleicht den in Git ge­spei­cher­ten Soll­zu­stand re­gel­mä­ßig mit dem Live-Zustand im Ku­ber­netes-Cluster.

Wird bei­spiels­wei­se ein De­ploy­ment manuell verändert, entsteht so­ge­nann­ter Con­fi­gu­ra­ti­on Drift. Wenn Git weiterhin drei Replikate definiert, ein Ad­mi­nis­tra­tor im Cluster jedoch manuell fünf Replikate kon­fi­gu­riert, un­ter­schei­den sich Soll- und Ist­zu­stand. Argo CD erkennt die Anwendung in diesem Fall als OutOfSync.

Ob Argo CD diese Ab­wei­chung lediglich meldet oder selbst kor­ri­giert, wird über die Sync Policy gesteuert. Mit

syncPolicy:
    automated:
        enabled: true

ak­ti­vie­ren Sie Automated Sync. Dadurch kann Argo CD Än­de­run­gen aus der be­ob­ach­te­ten Git-Revision au­to­ma­tisch auf den Cluster über­tra­gen, sobald die Anwendung OutOfSync ist. Die CI-Pipeline muss in diesem Modell lediglich die de­kla­ra­ti­ve Kon­fi­gu­ra­ti­on in Git ak­tua­li­sie­ren und benötigt keinen separaten De­ploy­ment-Aufruf an Argo CD oder Ku­ber­netes.

Für die au­to­ma­ti­sche Korrektur manueller Än­de­run­gen am Live-Cluster muss zu­sätz­lich Self-Healing aktiviert sein:

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 ent­spre­chen­de Git-Revision nicht geändert hat. Dadurch wird bei­spiels­wei­se eine manuelle Änderung am De­ploy­ment wieder auf den in Git fest­ge­leg­ten Wert zu­rück­ge­führt.

Optional können Sie zu­sätz­lich prune ak­ti­vie­ren:

syncPolicy:
    automated:
        enabled: true
        prune: true
        selfHeal: true

prune: true sorgt dafür, dass Argo CD zuvor ver­wal­te­te Res­sour­cen auch aus dem Cluster entfernt, wenn sie aus der ge­wünsch­ten Kon­fi­gu­ra­ti­on entfernt wurden. Da dies Lösch­ope­ra­tio­nen au­to­ma­ti­siert, sollte diese Ein­stel­lung bewusst ein­ge­setzt werden. Argo CD stellt für besonders kritische Res­sour­cen zu­sätz­li­che 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 klas­si­schen Rollback gleich­zu­set­zen. Self-Healing stellt den aktuell in Git de­fi­nier­ten Soll­zu­stand wieder her. Ein Rollback be­zeich­net dagegen den Wechsel auf eine frühere Revision. Argo CD behandelt Rollbacks als separaten Vorgang; für An­wen­dun­gen mit ak­ti­vier­tem Automated Sync ist ein solcher Rollback nicht direkt verfügbar, solange die au­to­ma­ti­sche Syn­chro­ni­sie­rung aktiv ist.

Git als Single Source of Truth

Der ent­schei­den­de or­ga­ni­sa­to­ri­sche Schritt beim Einsatz von Argo CD besteht darin, Git tat­säch­lich als Single Source of Truth zu behandeln. Än­de­run­gen an Ku­ber­netes-Res­sour­cen sollten deshalb nicht dauerhaft über manuelle kubectl-Befehle oder Än­de­run­gen in der Cluster-Ober­flä­che vor­ge­nom­men werden. Statt­des­sen wird die ge­wünsch­te Änderung in Git ein­ge­tra­gen, geprüft und ver­sio­niert.

Der daraus re­sul­tie­ren­de Ablauf ist klar definiert: Eine Kon­fi­gu­ra­ti­ons­än­de­rung wird zunächst in Git vor­ge­nom­men. Argo CD erkennt den neuen ge­wünsch­ten Zustand, rendert ge­ge­be­nen­falls Helm-Charts oder Kustomize-Kon­fi­gu­ra­tio­nen und ver­gleicht das Ergebnis mit den vor­han­de­nen Ku­ber­netes-Res­sour­cen. An­schlie­ßend syn­chro­ni­siert der Ap­pli­ca­ti­on Con­trol­ler die not­wen­di­gen Än­de­run­gen mit dem Cluster. Durch den fort­lau­fen­den Re­con­ci­lia­ti­on Loop werden spätere Ab­wei­chun­gen erneut erkannt und können über Self-Healing au­to­ma­tisch kor­ri­giert werden.

Dadurch bleibt nicht nur do­ku­men­tiert, welcher Zustand aktuell im Cluster vorhanden sein soll. Über die Git-Historie ist ebenfalls nach­voll­zieh­bar, wann eine Kon­fi­gu­ra­ti­on geändert wurde und welche Version zuvor verwendet wurde. Argo CD ergänzt diese ver­sio­nier­te Kon­fi­gu­ra­ti­on um die kon­ti­nu­ier­li­che tech­ni­sche Kontrolle, ob der tat­säch­li­che Ku­ber­netes-Zustand weiterhin mit dieser De­fi­ni­ti­on über­ein­stimmt.