Zurück zur Startseite

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 2 Custom Resource Definitions (CRD) in Kubernetes ein:
Applications und Projects

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

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 (derzeitig ist nur “in-cluster” möglich) in-cluster (https://kubernetes.default.svc)
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.

Haben Sie die gewünschten Informationen nicht gefunden?

Kontaktieren Sie unseren Support:

+41 44 637 40 40 Support Portal support@nine.ch