ArgoCD

Argo CD ist ein Dienst, der es Ihnen erlaubt, Applikationen mit Hilfe eines Gitops Workflows kontinuierlich auf NKE Cluster zu deployen.

Details

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

• deklarative und versionierte Applikations-Deployments
• Automatisierung und Nachvollziehbarkeit durch Gitops Workflows
• Unterstützung von Applikationsdeklarationen über Helm, kustomize und jsonnet
• Web UI für die Visualisierung von Kubernetes Ressourcen
• Git Webhook Integration zur kompletten Automatisierung von Deployments
• CLI (Command Line Interface) Applikationen
• Nachvollziehbarkeit für Anwendungsereignisse und API Aufrufe
• Parameter für Helm und ksonnet Applikationen können direkt in Argo CD überschrieben werden (vereinfacht das Deployment in Entwicklungsumgebungen)
• Grafana Metrics-Dashboard

Verfügbarkeit

Argo CD ist als optionaler Service für NKE verfügbar. Es kann über das Cockpit aktiviert und mit einer beliebigen Anzahl an NKE-Clustern verbunden werden.

Nutzung

Vor der Nutzung von Argo CD ist es wichtig zu verstehen, wie ein typischer Arbeitsablauf für Deployments aussehen sollte. Argo CD unterstützt ein kontinuierliches Deployment über einen gitops Workflow. Dazu 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, raten die Best Practice Empfehlungen streng davon ab.

Wenn 2 getrennte Git Repositories genutzt werden, kann ein typischer Entwicklungsablauf mit Argo CD 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, dass eine neue produktive Version der Applikation ausgerollt werden soll.
3. Nun startet eine CI Pipeline, welche die folgenden Schritte ausführt:

• Aufbau, Tagging 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 Image-Version des Containers 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 einfach der Commit im Konfigurations Git Repository 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 mit GitOps sinnvoll nutzen zu können, wird als Mindestanforderung Folgendes benötigt:

• die Adresse Ihrer Argo CD Installation (siehe Login)
• ein Kubernetes Namespace, in dem Argo CD Applikationen bereitstellen darf (siehe Namespace Erstellung)
• ein Git Repository, welches die Konfiguration Ihrer Applikation beinhaltet (auch Konfigurations Repo genannt). Die Konfiguration kann auf folgende Weise geschehen:
  • kustomize Deklarationen
  • ein Helm chart
  • ein Verzeichnis mit Kubernetes Ressourcen-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 von Nine bevorzugen Helm Charts, da wir Helm auch selbst innerhalb des Unternehmens nutzen.

Ein Beispiel für eine Helm Applikations-Konfiguration, die ein Gästebuch in einem Kubernetes Namespace bereitstellt, finden Sie im Argo Project Github Namespace im Verzeichnis helm-guestbook.

Berechtigungen

Das derzeitige Berechtigungskonzept gewährt allen eingetragenen NKE 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' besitzen nur Leserechte in Argo CD und können Argo CD Applikationen und Projekte nur ansehen, aber keine Änderungen vornehmen.

Login

Argo CD bietet sowohl ein Webinterface als auch eine CLI Anwendung zur Steuerung an.

Web UI

Die URL Ihrer Argo CD Installation finden Sie hier: Cockpit.

Auf der Login-Seite können Sie sich mit Ihrem Cockpit Account anmelden, nachdem Sie auf Login via Nine geklickt haben.

CLI

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

Um sich über die CLI Applikation einzuloggen, folgen Sie bitte den nachfolgenden 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 Nine Cockpit Nutzeraccount anmelden können
3. Nachdem Sie sich erfolgreich angemeldet haben, können Sie die argocd CLI Applikation lokal als authentifizierter Benutzer nutzen

Argo CD öffnet für die Authentifizierung mit Single Sign-on einen lokalen Port (standardmässig 8085) auf Ihrem Gerät. Sollte dieser Port bereits von einer anderen Applikation genutzt werden, wählen Sie bitte einen freien Port über das --sso-port Argument.

Konfigurations-Ressourcen in Argo CD

Argo CD führt 3 Custom Resource Definitions (CRD) in Kubernetes ein: Applications, Projects und ApplicationSets

Applications: Das Application CRD ist die Kubernetes Ressource, welche eine Applikation in einer bestimmten Umgebung beschreibt. Es wird von 2 Informationen definiert:

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

Im Grunde beschreibt das Application CRD, welche Applikations-Konfiguration in welchen Kubernetes Namespace innerhalb Ihres Clusters ausgerollt werden soll.

Projects: Das AppProject CRD ist eine Kubernetes Ressource, welche Applikationen in Projekten logisch zusammenfasst. Es wird von folgenden Informationen definiert:

• eine sourceRepos Referenz, welche die erlaubten Git Konfigurations-Repositories für Anwendungen im Projekt darstellt
• eine destinations Referenz, welche beschreibt, in welchen Clustern und Namespaces Anwendungen im Projekt ausgerollt werden dürfen
• eine Liste von Rollen-Entitäten und ihren jeweiligen Zugriffsrechten auf Ressourcen innerhalb des Projekts

ApplicationSets: ApplicationSets ermöglichen es Ihnen, die Erstellung von Applications zu automatisieren und die Multi-Cluster-Unterstützung zu verbessern.

ApplicationSets können nur über die Kommandozeile (CLI) erstellt werden.

Bitte sehen Sie sich die offizielle Dokumentation an, um zu erfahren, wie Sie ApplicationSets verwenden können.

Sollten Sie Probleme haben, ApplicationSets zum Laufen zu bringen, kontaktieren Sie bitte den Support.

App of Apps Prinzip

Beide CRDs können in Git Konfigurations-Repositories verwendet werden um das sogenannte "App of Apps Prinzip" umzusetzen. Dabei werden dabei die einzelnen Argo CD Anwendungen nicht (wie weiter unten beschrieben) im Web UI oder via CLI erstellt, sondern ebenfalls über Git definiert.

Bei einem "app of apps" Deployment spezifizert man eine Basis ArgoCD Applikation, welche dann wiederrum auf weitere ArgoCD Applikationen zeigt.

Bitte beachten Sie, dass ihre ArgoCD Installation auf einem externen Kubernetes Cluster läuft und sich daher nicht auf ihrem NKE Cluster befindet. Sollten Sie ArgoCD Applikations CRs (custom resources) anlegen, müssen diese einen speziellen Namespace haben, sowie auf dem 'in-cluster' Ziel Server appliziert werden. Sie können den zu verwendenden speziellen Namespace im Cockpit bei ihrer ArgoCD Instanz finden.

Hier eine Beispiel Basis Applikation welche ein Gästebuch via ArgoCD definiert.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: <spezieller Namespace Wert>
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    namespace: <spezieller Namespace Wert>
    name: in-cluster
  project: default
  source:
    path: guestbook
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD

Bereitstellen Ihrer Applikation mittels Argo CD

Namespace-Erstellung

Um Ihre Applikation mittels Argo CD bereitzustellen, wird ein Kubernetes Namespace benötigt, in dem Argo CD die entsprechenden Rechte besitzt, Ressourcen zu erstellen, zu ändern und zu löschen. Standardmässig hat Argo CD keine Rechte, Applikationen in beliebigen Namespaces innerhalb eines Clusters bereitzustellen. 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 weist Argo CD mit der entsprechenden Annotation die Rechte zu:

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

Argo CD besitzt nun die entsprechenden Rechte, um im Namespace my-application Applikationen bereitzustellen:

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

Name:         namespace-admins
<...>
Subjects:
  Kind            Name                           Namespace
  ----            ----                           ---------
  ServiceAccount  argocd-c3182374-mcj28sd        default
<...>

Erstellung einer Argo CD Applikation

Eine Argo CD Applikation beschreibt, welcher Konfigurationszustand einer Applikation in welchen Kubernetes Namespace Ihres Clusters bereitgestellt werden soll.

Dazu sollten Sie zuerst das Git Konfigurations-Repository in Argo CD erstellen, um dieses danach bei der Konfiguration 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.

Ein Hinweis zu SSH

Obwohl es möglich ist, das Git Konfigurations-Repository über SSH anzubinden, empfehlen wir die Nutzung von HTTPS. Sollten Sie auf eine Anbindung über SSH angewiesen sein, so müssen Sie zuerst den SSH public host key Ihres Git Providers konfigurieren, wie in der Argo CD Dokumentation beschrieben. 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-Schritte

Führen Sie die folgenden Schritte aus, um das Konfigurations-Repository über das Webinterface zu konfigurieren:

1. Loggen Sie sich im Web-UI 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

Punkt	Beschreibung	Beispiel
Repository URL	die HTTPS URL zum Git Konfigurations-Repository	https://gitlab.com/example/my-application-config
Username	der Nutzername für das Git Konfigurations-Repository (bitte verwenden Sie access tokens statt persönlichen Zugängen)	argocd
Password	das Passwort für das Git Konfigurations-Repository (bitte verwenden Sie access tokens statt persönlichen Zugängen)	3macm32449asdnf243rt
TLS client certificate	ein optionaler TLS Client Zertifikats-Schlüssel für die Anmeldung beim Git Repository (im PEM Format)
TLS client certificate key	ein optionales TLS Client Zertifikat für die Anmeldung beim Git Repository (im PEM Format)
skip server verification	aktivieren Sie diese Checkbox, wenn Argo CD das TLS Zertifikat des Git Providers nicht überprüfen soll
Enable LFS support	aktivieren 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

Punkt	Beschreibung	Beispiel
Application Name	der Name Ihrer Applikation	my-application
Project	das Projekt (siehe Projekte, welchem Ihre Applikation zugeordnet werden soll	default
Sync Policy	Wählen Sie zwischen manueller oder automatischer Synchronisation. Bei manueller Synchronisation müssen Sie Argo CD explizit anweisen, den aktuellen Stand des Konfigurations-Repositories zu synchronisieren (über Web UI oder CLI Applikation). Eine automatische Synchronisation überprüft den aktuellen Stand des Git Repos alle 3 Minuten. Sie können Webhooks einrichten, um diese Zeitspanne zu verkürzen.	Automatic
Source	die Quelle Ihres Konfigurations-Repositories (Sie sollten hier das soeben konfigurierte Repository auswählen können)	https://gitlab.com/example/my-application-config
Revision	Mithilfe der Revision können Sie den Git Branch, Tag oder Commit auswählen, welcher den gewünschten Konfigurationszustand der Applikation beschreibt. Dies kann z. B. zur Bereitstellung unterschiedlicher Umgebungen einer Applikation genutzt werden.	development
Path	Bitte spezifizieren Sie . als Pfad, wenn alle Ihre Konfigurationsdateien (Helm chart, kustomize files, etc.) im Root-Verzeichnis des Git Repositories liegen. Ansonsten können Sie hier ein Unterverzeichnis wählen, das nach Konfigurationsdateien durchsucht wird.	.
Cluster	der Cluster, welcher zur Bereitstellung genutzt werden soll	dein-cluster-name
Namespace	der Namespace, in dem die Applikation bereitgestellt werden soll (siehe hierzu Namespace Erstellung)	my-application
Type	der Konfigurationstyp (einfache yaml files, Helm chart, kustomize, etc.)	Helm
include subdirectories	Hier legen Sie fest, ob auch Unterverzeichnisse des Pfades durchsucht werden sollen.

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

Überschreiben von Parametern

Mitunter ist der Betrieb eines separaten Git Konfigurations-Repositories unnötig oder zu aufwändig. Dies kann beispielsweise in Entwicklungs- oder Testumgebungen der Fall sein. In diesen Fällen möchte man meistens:

• schneller iterieren
• upstream Helm Charts nutzen, ohne diese vorher in ein eigenes 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 Konfigurations-Repository speichern möchte.

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

Durch das Überschreiben der Parameter (z. B. in einem Helm Chart) werden die Konfigurations-Informationen direkt an Argo CD bereitgestellt, ohne dass ein Commit an ein Konfigurations-Repository nötig ist.

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 wird angewiesen, 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 wird angewiesen, die Applikation zu synchronisieren, indem argocd app sync ausgeführt wird

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

Fortgeschrittene Themen

Projekte

Projekte werden in Argo CD genutzt, um Applikationen logisch zu gruppieren. Weitere Informationen dazu finden Sie in der offiziellen Argo CD Dokumentation. Aufgrund einiger Restriktionen ist es derzeitig nicht möglich, RBAC Regeln für Projekte in NKE zu definieren.

Ein Einsatzzweck von Projekten ist die Erstellung von Rollen. Mit Rollen können Sie beispielsweise CI/CD Pipelines Zugriff auf Argo CD Applikationen geben (um diese beispielsweise zu synchronisieren), indem JWT Tokens genutzt werden, die den einzelnen Rollen zugewiesen sind.

Es folgt ein Beispiel für eine Rolle "cicd", welche alle Argo CD Applikationen des default Projekts synchronisieren darf:

argocd proj role create default cicd
argocd proj role create-token default cicd # save this token somewhere
argocd proj role add-policy default cicd -a sync -o '*' -p 'allow'

In der Pipeline können Sie die Applikationen dann folgendermassen synchronisieren:

argocd app sync <app name> --auth-token <your auth token>

Webhooks

Mit Webhooks kann Ihr Git Service Anbieter (Gitlab, Github, etc.) Argo CD informieren, sobald es Änderungen am Git Konfigurations-Repository gibt. Ohne Webhooks 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 finden Sie im Cockpit.

Dokumentation und Links

• Argo CD Architektur
• Argo CD Dokumentation für Entwickler