Zum Hauptinhalt springen

Argo CD

Argo CD ist ein Dienst von nine Managed GKE der es erlaubt Applikationen mit Hilfe eines Gitops Workflows kontinuierlich zu deployen.

Details​

Für Kunden welche kontinuierlich neuen Applikations Code deployen müssen, bietet Argo CD folgende Features:

  • deklarative und versionierte Applikations Deployments
  • Automatisierung und Nachvollziehbarkeit durch Gitops
  • Applikationsdeklarationen via helm, kustomize und jsonnet
  • Web UI für die Visualisierung von Kubernetes Resourcen
  • Git Webhook Integration
  • CLI (command line interface) Applikation
  • Nachvollziehbarkeit für Anwendungsereignisse und API Aufrufe
  • Parameter für helm und ksonnet Applikationen können direkt in Argo CD überschrieben werden (bspw. für Entwicklungsumgebungen)
  • Grafana Dashboard

Verfügbarkeit​

Argo CD ist standardmässig Teil von nine Managed GKE.

Nutzung​

Bevor man Argo CD nutzt, ist es wichtig zu verstehen wie ein typischer Arbeitsablauf für Deployments aussieht. Argo CD unterstützt kontinuierliche Deployments, durch die Nutzung von Gitops Techniken. Um eine bestmögliche Nutzung zu gewährleisten, empfiehlt es sich, die Konfiguration (helm charts, kustomize yaml Dateien, etc) vom eigentlichen Applikations Code zu trennen. Dies sollte durch die Benutzung von 2 getrennten Git Repositories geschehen. Obwohl es technisch möglich wäre nur ein Git Repository zu nutzen, sollte man aufgrund der Best Practice Empfehlungen von Argo CD eine Aufspaltung in 2 Repositories anstreben.

Sobald man 2 getrennte Git Repositories nutzt, könnte ein typischer Entwicklungsablauf so aussehen:

  1. ein Entwickler erstellt einen Pull oder Merge Request um seine Änderungen in den Master Branch des Code Repositories zu übernehmen
  2. nachdem die Änderungen übernommen (und alle Tests bestanden) wurden, erstellt der Entwickler einen Git Tag um zu signalisieren das eine neue produktive Version der Applikation ausgerollt werden soll
  3. aufgrund des Tags startet eine CI pipeline welche die folgenden Schritte ausführt:
  • Bauen, taggen und heraufladen eines neuen Container Applikations Images
  • Erstellung eines Commits im Konfigurations Git Repository, welcher die neue Image Version als produktiv spezifiziert (bspw. durch Änderung eines keys in der Datei values.yaml eines Helm Charts)
  • Pushen des Commits
  1. (optional) Auslösen eines Webhooks welcher Argo CD dazu veranlasst den aktuellen Stand des Konfigurations Git Repositories zu synchronisieren
  2. Argo CD rollt die neue Version der Applikation aus

Argo CD ist beim gesamten Ablauf nicht mit dem Applikations Code Repository verbunden. Es existiert lediglich eine Verbindung zum Konfigurations Git Repository (hier sind Leseberechtigungen ausreichend).

Sollte es beim genannten Ablauf zu Problemen mit der neuen Applikationsversion kommen, so kann die vorhergehende Version sehr einfach wiederhergestellt werden. Es muss dazu der Commit im Konfigurations Git Repository einfach rückgängig gemacht werden. Argo CD nimmt die Änderung automatisch auf und rollt danach die vorhergehende Version wieder aus.

Um eine striktere Trennung zwischen Applikations Code und Konfigurations Code herzustellen, ist es auch möglich in der CI pipeline einen Merge/Pull Request für das Konfigurations Repo zu erstellen (statt eines direkten Commits). Dieser Request muss dann von entsprechend zuständigen Personen genehmigt werden, bevor die neue Applikationsversion ausgerollt wird. Somit ist es möglich Entwicklern Zugriff auf das Applikations Code Repository zu geben, ohne dass diese die laufende Produktionsversion ändern können.

Voraussetzungen​

Um Argo CD für produktive Deployments sinnvoll nutzen zu können, wird folgendes benötigt:

  • die Adresse ihrer Argo CD Installation (zu finden unter runway)
  • ein Kubernetes Namespace in dem Argo CD Applikationen bereitstellen darf (siehe Namespace Erstellung
  • ein Git Repository welches die Konfiguration ihrer Applikation beinhalten (auch Konfigurations Repo genannt). Die Konfiguration kann auf folgende Weise geschehen:
    • kustomize Deklarationen
    • ein helm chart
    • ein Verzeichnis mit Kubernetes Resourcen Deklarationen (yaml Dateien)
    • jsonnet Deklarationen
  • ein CI/CD Dienst um:
    • Container Images automatisch erstellen zu lassen
    • automatische Änderungen im Konfigurations Repository durchzuführen (optional)

Wir bei nine präferieren die Nutzung von Helm Charts im Konfigurations Repository, da wir Helm innerhalb der Firma überwiegend nutzen.

Eine Beispielapplikation weche ein Gästebuch in einem Kubernetes Namespace bereit stellt, kann im Argo Project Github Namespace im Verzeichnis helm-guestbook gefunden werden.

Berechtigungen​

Das derzeitige Berechtigungskonzept gewährt allen eingetragenen nine Managed GKE Benutzern mit einer der folgenden Rollen, vollen Zugriff auf alle Argo CD Applikationen und Projekte ihrer jeweiligen Argo CD Installation:

  • admin
  • user

Benutzer mit der Rolle 'viewer' besitzten nur Leserechte in Argo CD und können keine Änderungen vornehmen.

Login​

Argo CD bietet ein Webinterface, sowie auch eine CLI Anwendung zur Steuerung an.

Web UI​

Sie können die URL ihrer Argo CD Installation auf unserer runway Seite finden.

Auf der Login Seite von Argo CD können Sie sich mit ihrem ninegcp.ch Nutzeraccount anmelden, indem Sie auf Login via keycloak klicken.

CLI​

Die zu Ihrer Argo CD Installation passende CLI Applikation können Sie auf der Hilfe Seite im Argo CD Web UI herunterladen (sie können einen Link zur Hilfe Seite im Navigationsmenü auf der linken Seite finden).

Um sich via CLI Applikation einzuloggen, folgen Sie bitte den nachfolgende Schritten:

  1. führen sie argocd login <Argo CD URL> --sso lokal in einem Terminal aus
  2. argocd öffnet daraufhin eine Webseite, auf welcher sie sich mit ihrem ninegcp.ch Nutzeraccount anmelden können
  3. nachdem Sie sich erfolgreich angemeldet haben, können sie die argocd CLI Applikation als authentifizierter Benutzer nutzen

Argo CD öffnet für die Authentifizierung einen lokalen Port (standardmässig 8085) auf ihrer Maschine. Sollte dieser Port bereits in Nutzung von einer anderen Applikation sein, so wählen Sie bitte einen freien Port über das --sso-port Argument.

Konfigurations Resourcen in Argo CD​

Argo CD führt 2 custom resource definitions (CRD) in Kubernetes ein: Applications und Projects

Applications: Das Applications CRD ist eine Kubernetes Resource welche eine Applikation in einer bestimmten Umgebung beschreibt. Es wird von 2 Informationen geprägt:

  • eine source Referenz welche das gewünschte Git Konfigurations Repository beschreibt (Repository URL, Revision, Pfad, Konfigurationstyp)
  • eine destination Referenz welche beschreibt in welchem Cluster und Namespace die Applikation ausgerollt werden soll

Im Grunde beschreibt es welche Applikations-Konfiguration in welchen Kubernetes Namespace innerhalb des nine Managed GKE Clusters ausgerollt werden soll.

Projects: Das AppProject CRD ist eine Kubernetes Resource welche Applikationen in Projekten logisch zusammenfasst. Es wird von folgenden Informationen geprägt:

  • eine sourceRepos Referenz welche die erlaubten Git Konfigurations Repositories für Anwendungen im Projekt darstellt
  • eine destinations Referenz welche beschreibt in welche Cluster und Namespaces Anwendungen im Projekt ausgerollt werden dürfen
  • eine Liste von Rollen Entitäten und Ihren jeweiligen Rechten für Objekte im Projekt

Beide CRDs können in Git Konfigurations Repositories verwendet werden um das sogenannte "App of Apps Prinzip" zu ermöglichen. Dabei werden die einzelnen Argo CD Anwendungen nicht (wie weiter unten beschrieben) im Web UI oder via CLI erstellt, sondern ebenfalls via Git definiert. Bitte beachten Sie das der Namespace Ihrer Argo CD Installation nine-argocd ist und nicht argocd wie in den Beispielen verwendet.

Bereitstellen Ihrer Applikation mittels Argo CD​

Namespace Erstellung​

Um ihre Applikation mittels Argo CD bereit zu stellen, wird ein Kubernetes Namespace benötigt in dem Argo CD die entsprechenden Rechte besitzt Resourcen zu erstellen, zu ändern und zu löschen. Standardmässig hat Argo CD keine Rechte Applikationen in Kunden Namespaces bereit zu stellen. Sie müssen diese Rechte explizit durch die Namespace Annotation nine.ch/argo-admin="true" an Argo CD zuweisen.

Das folgende Beispiel erstellt einen Namespace my-application and fügt die entsprechende Annotation hinzu:

kubectl create namespace my-application
kubectl annotate namespace/my-application nine.ch/argo-admin="true"

Argo CD besitzt nun die entsprechenden Rechte im Namespace my-application, Applikationen bereit zu stellen:

$> kubectl describe rolebinding namespace-admins -n my-application

Name:         namespace-admins
<...>
Subjects:
  Kind            Name                           Namespace
  ----            ----                           ---------
  ServiceAccount  argocd-server                  nine-argocd
  ServiceAccount  argocd-application-controller  nine-argocd
<...>

Erstellung einer Argo CD Applikation​

Eine Argo CD Applikation beschreibt welcher Konfigurationszustand einer Applikation in welchen Kubernetes Namespace ihres nine Managed GKE clusters bereit gestellt werden soll.

Sie sollten zuerst das Git Konfigurations Repository in Argo CD erstellen um dieses danach in einer Argo CD Applikation nutzen zu können.

Das Repository, sowie die Applikation selbst, kann via Web UI oder CLI Applikation konfiguriert werden. Die folgende Dokumentation zeigt eine exemplarische Konfiguration über das Webinterface.

SSH Verbindung zum Konfigurations Repo​

Obwohl es möglich ist das Git Konfigurations Repository via SSH anzubinden, empfehlen wir die Nutzung von HTTPS. Sollten Sie auf eine Anbindung via SSH angewiesen sein, so müssen sie zuerst den SSH public host key Ihres Git Providers, wie in der Argo CD Dokumentation beschrieben konfigurieren. Diesen Schritt benötigen Sie nicht, wenn Sie das Repo mittels HTTPS Protokoll anbinden. Bitte achten Sie bei der Nutzung von HTTPS stets darauf ein vertrauenswürdiges TLS Zertifikat zu nutzen.

Konfigurations Repository konfigurieren​

Führen Sie die folgenden Schritte aus, um das Konfigurations Repository via Web interface zu konfigurieren:

  1. Loggen Sie sich via Webinterface ein (siehe Login)
  2. Klicken Sie auf das Zahnrad icon im Menü links ("Manage your repositories,projects,settings")
  3. Klicken Sie auf Repositories
  4. Klicken Sie auf Connect repo using https
  5. Nun können Sie die Zugangsdetails für das Repository eingeben
PunktBeschreibungBeispiel
Repository URLDie HTTPS URL zum Git Konfigurationsrepositoryhttps://gitlab.com/example/my-application-config
Usernameder Nutzername für das Git Konfigurationsrepository (bitte benutzen Sie access tokens statt persönlichen Zugängen)argocd
Passworddas Passwort für das Git Konfigurationsrepository (bitte benutzen Sie access tokens statt persönlichen Zugängen)3macm32449asdnf243rt
TLS client certificateein optionaler TLS Client Zertifikats Schlüssel für die Anmeldung am Git Repository (im PEM Format)
TLS client certificate keyein optionales TLS Client Zertifikat für die Anmeldung am Git Repository (im PEM Format)
skip server verificationaktivieren Sie diese Checkbox falls Argo CD das TLS Zertifikat des Git Providers nicht überprüfen soll
Enable LFS supportaktivieren Sie diese Checkbox falls Sie "Git large file support" in Ihrem Repository nutzen

Nachdem sie das Git Repository registriert haben, können Sie nun die Argo CD Applikation anlegen

  1. Klicken Sie auf New Application (in der oberen linken Bildschirmecke) auf der Hauptseite Ihrer Argo CD Installation
  2. Sie können nun die Applikations Details eingeben
PunktBeschreibungBeispiel
Application Nameder Name ihrer Applikationmy-application
Projectdas Projekt (siehe Projekte welches Ihre Applikation zugeordnet werden solldefault
Sync Policywählen Sie zwischen manueller oder automatischer Synchronisation. Bei manueller Synchronisation müssen Sie Argo CD explizit anweisen den aktuellen Stand des Konfigurationsrepositories zu synchroniseren (via Web UI oder CLI Applikation). Eine automatische Synchronisation wird den aktuellen Stand des Git Repos alle 3 Minuten überprüfen. Sie können Webhooks einrichten um diese Zeitspanne zu verkürzen.Automatic
Sourcedie Quelle ihres Konfigurationsrepositories (sie sollten hier das soeben konfigurierte Repository auswählen können)https://gitlab.com/example/my-application-config
Revisionmithilfe der Revision können Sie den Git Branch, Tag oder Commit auswählen welcher den gewünschten Konfigurationszustand der Applikation beschreibt. Dies kann beispielsweise genutzt werden um unterschiedliche Umgebungen einer Applikation bereit zu stellen.development
Pathbitte spezifizeren Sie . als Pfad falls ihre Konfigurationsdateien (helm chart, kustomize Dateien, etc) im Root Verzeichnis des Git Repositories liegen. Ansonsten können Sie hier ein Unterverzeichnis wählen, was nach Konfigurationsdateien durchsucht wird.
Clusterder Cluster welcher zur Bereitstellung genutzt werden soll (derzeitig ist nur "in-cluster" möglich)in-cluster (https://kubernetes.default.svc)
Namespaceder Namespace in dem die Applikation bereitgestellt werden soll (siehe hierzu Namespace Erstellung)my-application
Typeder Konfigurationstyp (einfache yaml files, helm chart, kustomize, etc).Helm
include subdirectoriessollen Unterverzeichnisse des Pfades auch durchsucht werden

Falls Sie Helm Charts als Konfigurationstyp nutzen, so ist es auch möglich mehrere value.yaml Dateien anzugeben. Diese werden dann in der vorgegebene Reihenfolge zusammengeführt.

Überschreiben von Parametern​

Unter bestimmten Umständen kann es sein dass der Betrieb eines seperaten Git Konfigurations Repositories zu aufwändig ist. Dies kann beispielsweise in Entwicklungs- oder Testumgebungen der Fall sein. In diesen Fällen möchte man meistens:

  • schnell iterieren
  • upstream Helm Charts nutzen ohne diese vorher in ein eigene Git Repository transferieren zu müssen

Ein weiterer Anwendungsfall wäre, dass man Passwörter oder Zugangsdaten in der Konfiguration benötigt, diese aber nicht im Git Repository speichern möchte.

Für derartige Szenarien bietet Argo CD die Möglichkeit direkt Parameter einer Applikation zu überschreiben ohne dafür ein Git Repository nutzen zu müssen. Das Überschreiben von Parametern ist nur möglich falls Sie ihre Applikation mithilfe von Helm Charts oder ksonnet konfigurieren.

Wird beispielsweise ein Helm Chart als Konfigurationsmethode genutzt, so ist es möglich direkt Werte der Datei values.yaml zu überschreiben.

Ein möglicher Workflow ohne Git Repository könnte dann wie folgt aussehen:

  1. ein Entwickler konfiguriert eine Argo CD Applikation welche ein öffentlich verfügbares Helm Chart nutzt (entweder in einem öffentlichen Git Repository oder einem Helm Chart Repository)
  2. die Entwicklung der Applikation findet in einem Feature Branch statt
  3. sobald der Entwickler seine Änderungen ins Applikations Code Repository überträgt, startet eine CI pipeline welche die folgenden Schritte ausführt:
  • Erstellen und Hochladen eines neuen Container Images
  • Argo CD anweisen die soeben erstellte Version zu nutzen. Dies geschieht mittels CLI Applikation ( argocd app ...) und dem überschreiben des image tag (Parameter) der values.yaml Datei des öffentlich verfügbaren Helm Charts.
  • Argo CD anweisen die Applikation zu synchroniseren (argocd app sync)

Das Überschreiben von Parametern ist via CLI Applikation oder im Webinterface von Argo CD möglich.

Fortgeschrittene Themen​

Projekte​

Projekte werden in Argo CD genutzt um Applikationen logisch zu gruppieren. Sie können mehr Informationen darüber in der offiziellen Argo CD Dokumentation lesen. Aufgrund einiger Restriktionen ist es derzeitig nicht möglich RBAC Regeln für Projekte in nine Managed GKE Clustern zu definieren.

Ein Einsatzzweck für Prokekte ist die Erstellung von Rollen. Mittels Rollen können Sie beispielsweise CI/CD pipelines nur auf bestimmte Argo CD Applikationen Zugriff geben (um diese beispielsweise zu synchroniseren oder Parameter zu überschreiben), da sich für jede Rolle JWT Tokens generieren lassen. Mithilfe dieser Tokens kann man sich innerhalb der argocd CLI Applikation als die entsprechende Rollen authentifizieren.

Hier ist ein Beispiel für eine Rolle "cicd" welche in der Lage ist alle Argo CD Applikationen des default Projekts zu synchronisieren.

argocd proj role create default cicd
argocd proj role create-token default cicd # speichern sie den ausgegeben Token an einem sicheren Ort
argocd proj role add-policy default cicd -a sync -o '*' -p 'allow'

In einer CI/CD Pipeline kann man diese Rolle dann wie folgt nutzen:

argocd app sync <app name> --auth-token <ihr Authentifizierungs Token>

Webhooks​

Mittels Webhooks kann ihr Git Service Anbieter (Gitlab, Github, etc) Argo CD informieren sobald es Änderungen am Git Konfigurations Repository gab. Sobald Argo CD über einen Webhook informiert wird, löst es eine Synchronisierung der Argo CD Applikation des entsprechende Git Repositories aus. Ohne den Einsatz von Webhooks (und bei Einsatz einer automatischen Synchronisierung) prüft Argo CD alle 3 Minuten den derzeitigen Zustand des Git Repositories. Sie müssen die Webhook Konfiguration bei ihrem Git Service Anbieter vornehmen. Die Ziel URL für Argo CD und das vorkonfigurierte Passwort entnehmen Sie bitte der runway Seite.