Zum Hauptinhalt springen

ArgoCD

Argo CD ist ein Dienst, der es dir 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 deiner Argo CD Installation (siehe Login)
  • ein Kubernetes Namespace, in dem Argo CD Applikationen bereitstellen darf (siehe Namespace Erstellung)
  • ein Git Repository, welches die Konfiguration deiner 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, findest du 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 deiner 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 deiner Argo CD Installation findest du hier im Cockpit.

Auf der Login-Seite kannst du dich mit deinem Cockpit Account anmelden, nachdem du auf Login via Nine geklickt hast.

CLI​

Die zu deiner Argo CD Installation passende CLI Applikation kannst du auf der Hilfe Seite im Argo CD Web UI herunterladen. (du findest einen Link zur Hilfe Seite im Navigationsmenü auf der linken Seite.)

Um dich über die CLI Applikation einzuloggen, folge bitte den nachfolgenden Schritten:

  1. Führe argocd login <Argo CD URL> --sso lokal in einem Terminal aus
  2. argocd öffnet daraufhin eine Webseite, auf welcher du dich mit deinem Nine Cockpit Nutzeraccount anmelden kannst
  3. Nachdem du dich erfolgreich angemeldet hast, kannst du 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 deinem Gerät. Sollte dieser Port bereits von einer anderen Applikation genutzt werden, wähle 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 deines 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 dir, 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 sieh dir die offizielle Dokumentation an, um zu erfahren, wie du ApplicationSets verwenden kannst.

Solltest du Probleme haben, ApplicationSets zum Laufen zu bringen, kontaktiere 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 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 weitere ArgoCD Applikationen erstellt.

Bitte beachte, dass deine ArgoCD Installation auf einem externen Kubernetes Cluster läuft und sich daher nicht auf deinem NKE Cluster befindet. Die ArgoCD Basis Applikation sollte daher die generierten Applikationen in einem speziellen Namespace anlegen und auch das spezielle 'in-cluster' Ziel verwenden. Der Namespace ist dabei das Projekt, in welchem deine ArgoCD Instanz erstellt wurde. Du kannst den Projektnamen in den Zugangsdetails deiner ArgoCD Instanz im Cockpit finden.

Hier eine Beispiel Basis Applikation, welche wiederrum eine Gästebuch Applikation erzeugt. Die Basis Applikation zeigt dabei auf das Verzeichnis "apps" eines ArgoCD Beispiel Git Repositories. Dieses Verzeichnis enthält ein Helm Chart was wiederrum andere ArgoCD Applikationen generiert. Die URL für den NKE Ziel Cluster kannst du im Web-UI deiner ArgoCD Instanz unter "Settings" -> "Clusters" finden.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: basis
spec:
  destination:
    name: in-cluster
  project: default
  source:
    path: apps
    repoURL: https://github.com/ninech/argocd-example-apps
    targetRevision: HEAD
    helm:
      values: |
        config:
          argocdNamespace: <Projekt deiner ArgoCD Instanz>
          spec:
            destination:
              server: <ArgoCD Ziel URL des NKE Clusters>
            source:
              repoURL: https://github.com/ninech/argocd-example-apps
              targetRevision: master
        applications:
          - name: guestbook
            # der namespace Parameter setzt den Installations Namespace auf dem
            # Ziel NKE Cluster fest
            namespace: guestbook

Du kannst diese Definition in einer Datei speichern und sie mit Hilfe des ArgoCD CLIs anwenden. Bitte folge den dokumentierten Login Schritten für das ArgoCD CLI. Weiterhin solltest du den Ziel Namespace ("guestbook" im Beispiel) bereits, wie dokumentiert, in deinem NKE Cluster erstellt haben. Erstelle die Basis Applikation dann mittels dem folgenden Befehl.

argocd app create --file=<Pfad zur Applikations yaml Datei>

Nachdem die Basis Applikation angelegt wurde, wird sie eine neue "guestbook" Applikation erstellen, welche eine Gästebuch Applikation auf deinem NKE Cluster installieren wird.

Bereitstellen deiner Applikation mittels Argo CD​

Namespace-Erstellung​

Um deine 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. Du musst 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 deines Clusters bereitgestellt werden soll.

Dazu solltest du 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. Solltest du auf eine Anbindung über SSH angewiesen sein, so musst du zuerst den SSH public host key deines Git Providers konfigurieren, wie in der Argo CD Dokumentation beschrieben. Diesen Schritt benötigst du nicht, wenn du das Repo mittels HTTPS Protokoll anbindest. Bitte achte bei der Nutzung von HTTPS stets darauf, ein vertrauenswürdiges TLS Zertifikat zu nutzen.

Konfigurations-Schritte​

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

  1. Logge dich im Web-UI ein (siehe Login)
  2. Klicke auf das Zahnrad Icon im Menü links ("Manage your repositories,projects,settings")
  3. Klicke auf Repositories
  4. Klicke auf Connect repo using https
  5. Nun kannst du die Zugangsdetails für das Repository eingeben
PunktBeschreibungBeispiel
Repository URLdie HTTPS URL zum Git Konfigurations-Repositoryhttps://gitlab.com/example/my-application-config
Usernameder Nutzername für das Git Konfigurations-Repository (bitte verwende access tokens statt persönlichen Zugängen)argocd
Passworddas Passwort für das Git Konfigurations-Repository (bitte verwende access tokens statt persönlichen Zugängen)3macm32449asdnf243rt
TLS client certificateein optionaler TLS Client Zertifikats-Schlüssel für die Anmeldung beim Git Repository (im PEM Format)
TLS client certificate keyein optionales TLS Client Zertifikat für die Anmeldung beim Git Repository (im PEM Format)
skip server verificationaktiviere diese Checkbox, wenn Argo CD das TLS Zertifikat des Git Providers nicht überprüfen soll
Enable LFS supportaktiviere diese Checkbox, falls du "Git large file support" in deinem Repository nutzt

Nachdem du das Git Repository registriert hast, kannst du nun die Argo CD Applikation anlegen

  1. Klicke auf New Application (in der oberen linken Bildschirmecke) auf der Hauptseite deiner Argo CD Installation
  2. Du kannst nun die Applikations-Details eingeben
PunktBeschreibungBeispiel
Application Nameder Name deiner Applikationmy-application
Projectdas Projekt (siehe Projekte, welchem deine Applikation zugeordnet werden solldefault
Sync PolicyWähle zwischen manueller oder automatischer Synchronisation. Bei manueller Synchronisation musst du 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. Du kannst Webhooks einrichten, um diese Zeitspanne zu verkürzen.Automatic
Sourcedie Quelle deines Konfigurations-Repositories (du solltest hier das soeben konfigurierte Repository auswählen können)https://gitlab.com/example/my-application-config
RevisionMithilfe der Revision kannst du 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
PathBitte spezifiziere . als Pfad, wenn alle deine Konfigurationsdateien (Helm chart, kustomize files, etc.) im Root-Verzeichnis des Git Repositories liegen. Ansonsten kannst du hier ein Unterverzeichnis wählen, das nach Konfigurationsdateien durchsucht wird..
Clusterder Cluster, welcher zur Bereitstellung genutzt werden solldein-cluster-name
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 subdirectoriesHier lege fest, ob auch Unterverzeichnisse des Pfades durchsucht werden sollen.

Falls du Helm Charts als Konfigurationstyp nutzt, 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 du deine Applikation mithilfe von Helm Charts oder ksonnet konfigurieren möchtest.

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 findest du 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 kannst du 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 kannst du die Applikationen dann folgendermassen synchronisieren:

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

Webhooks​

Mit Webhooks kann dein 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. Du musst die Webhook Konfiguration bei deinem Git Service Anbieter vornehmen. Die Ziel-URL für Argo CD und das vorkonfigurierte Passwort findest du im Cockpit.

Exkludierte Ressourcen​

Die folgenden Kubernetes Typen haben einen potentiellen Einfluss auf unser Backup Management System und die Art und Weise wie Backups erstellt werden. Sie werden daher standardmässig von der Synchronisation ignoriert:

  • snapshot.storage.k8s.io/VolumeSnapshot
  • snapshot.storage.k8s.io/VolumeSnapshotContent

Falls du die genannten Ressourcen in deiner ArgoCD Applikation einsetzt, so werden diese nicht auf den Cluster synchronisiert werden. Falls das deinen gewünschten Einsatzzweck affektiert, zögere bitte nicht, uns zu kontaktieren.