ArgoCD in der Praxis: Installation, Konfiguration und Application

Im ersten Teil dieser Serie haben wir uns mit GitOps beschäftigt und uns mit Vorteilen und Features der Tools Flux & ArgoCD vertraut gemacht.

Nun werden wir aktiv: In diesem Artikel wollen wir uns ArgoCD näher ansehen - von der Installation & Konfiguration bis hin zum Deployment von Services. Dabei werden wir auch die Kernkonzepte von ArgoCD in der Praxis kennen lernen: Application, AppProject und ApplicationSet.

Als Use Case wird uns dabei eine simple Demo-Helm-Applikation mit Frontend und Backend dienen – zunächst als einfaches Deployment, später in verschiedenen Umgebungen. Die Ausgangsbasis dabei: Unsere Demo-App liegt in GitLab, enthält einen funktionierenden Build-Prozess und wurde bereits mindestens einmal erfolgreich ins Cluster deployt.

Voraussetzungen

Falls ihr direkt mit ausprobieren möchtet, benötigt ihr die folgenden Komponenten:

Ein Git-Repository mit Helm-Charts für frontend und backend
Eine GitLab Pipeline, in der die Images gebaut und in die GitLab Container Registry gepusht werden.
Ein Kubernetes-Cluster mit Zugriff auf die GitLab Registry (bspw. via Gitlab Deploy Token als Secret, auf das im Helm Chart referenziert wird)

Installation von ArgoCD und ArgoCD CLI

Zur Installation benötigen wir zunächst einen dedizierten Namespace für ArgoCD via

kubectl create namespace argocd

Im Anschluss können wir ArgoCD direkt in unser Cluster installieren:

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Dabei werden u.a. die folgenden Kubernetes-Ressourcen erstellt:

argocd-server: Web-UI und API von ArgoCD, mit der wir später interagieren werden.
argocd-repo-server: Rendert Helm- oder Kustomize-Templates gemäß der (später noch anzugebenden) Git-Repositories.
argocd-application-controller: Überwacht die ArgoCD Applications und gleicht den gewünschten mit dem tatsächlichen Zustand im Cluster ab.
argocd-dex-server: (Optional) Identity Provider für Single Sign-On (kann deaktiviert oder ersetzt werden).
argocd-redis: Redis-Instanz als Cache für Metadaten.

Weitere Ressourcen wie argocd-cm, argocd-rbac-cm steuern zentrale Aspekte der ArgoCD-Konfiguration.

Um direkt und ohne UI mit dem argocd-server kommunizieren zu können, bietet sich außerdem noch die Installation der ArgoCD CLI an:

# Für Linux
curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x argocd
sudo mv argocd /usr/local/bin/

# Für macOS
brew install argocd

# Für Windows
choco install argocd

Nun haben wir alle ArgoCD Komponenten, um mit der Vorbereitung des Deployments beginnen zu können.

ArgoCD Dashboard

Auch wenn wir in diesem Artikel primär mit der CLI arbeiten werden, lohnt sich ein kurzer Blick in die UI. Dafür benötigen wir zunächst ein port-forwarding

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

sowie das Admin-Passwort, das ArgoCD automatisch für uns erstellt hat:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

Das Passwort aus unserem Terminal können wir dann direkt mit Username "admin" auf localhost verwenden und einen Blick auf das Dashboard werfen.

Unter Settings -> Cluster sehen wir, dass unser Cluster schon direkt angebunden ist. Mit der URL

https://kubernetes.default.svc

können wir es damit in den folgenden Schritten referenzieren.

Anbindung des GitLab Repositories

Damit ArgoCD mit unserem GitLab Repository interagieren kann, müssen wir dieses zunächst durch ein Gitlab Deploy Token mit "Read Repository" Berechtigung anbinden:

Im Gitlab Repository unter Settings -> Repository -> Deploy tokens ein Token mit den entsprechenden Berechtigungen anlegen
Name und Passwort des Tokens direkt kopieren (später kann das Passwort nicht mehr angezeigt werden)

Nachdem wir unser Token erstellt haben, loggen wir uns in unserem Terminal in den ArgoCD Server ein via

argocd login localhost:8080 \
  --insecure \
  --username admin \
  --password $(kubectl get secret \
  -n argocd \
  argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" |
  base64 -d)

und fügen unser Repository durch

argocd repo add <repository link> --username <deploy-token-name> --password <deploy-token-password>

hinzu.

Nach erfolgreichem Update im Terminal können wir nun auch direkt im Dashboard unter Settings -> Repositories den Status unseres Repositories einsehen - der natürlich im besten Fall direkt successful meldet.

Deployment unserer Applikation

Nachdem nun alle relevanten Komponenten miteinander verbunden sind, können wir uns ans Deployment machen. Hier kommen die Eingangs erwähnten Kernkonzepte Application, AppProject und ApplicationSet ins Spiel:

Application: Eine ArgoCD Application beschreibt, was deployt werden soll – aus welchem Git-Repo, in welchen Cluster, in welchen Namespace. Sie ist die grundlegende Einheit, mit der ArgoCD den Abgleich von Git und Kubernetes steuert.

AppProject: Projekte definieren Rahmenbedingungen für Applications – zum Beispiel, welche Repositories erlaubt sind, in welche Namespaces deployed werden darf oder welche Cluster genutzt werden können. Besonders hilfreich bei mehreren Teams oder Umgebungen wie dev, stage und `prod auf verschiedenen Clustern.

`ApplicationSet: ApplicationSets ermöglichen die automatisierte Erstellung mehrerer Applications nach einem bestimmten Muster – z. B. je Umgebung, je Region oder je Instanz. Damit lassen sich viele ähnliche Deployments mit wenig Aufwand verwalten.

Für unseren simplen Demo-Use-Case wollen wir im ersten Schritt nur Applications in der Umgebung `dev anlegen.

ArgoCD Application anlegen

Zunächst definieren wir zwei einzelne Applications – eine für unser Frontend, eine für unser Backend.

frontend.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: frontend-dev
  namespace: argocd
spec:
  project: default
  source:
    targetRevision: main
    repoURL: <Repository Link>
    path: <Pfad zum Helm Chart>
    helm:
      valueFiles:
        - values/dev.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: dev 
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

backend.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: backend-dev
  namespace: argocd
spec:
  project: default
  source:
    targetRevision: main
    repoURL: <Repository Link>
    path: <Pfad zum Helm Chart>
    helm:
      valueFiles:
        - values/dev.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: dev 
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Diese beide Applications können wir nun in unser Cluster deployen via

kubectl apply -f frontend.yaml
kubectl apply -f backend.yaml

Nachdem nun beide Anwendungen für unsere Dev-Umgebung in ArgoCD eingerichtet sind, übernimmt das Tool künftig die Steuerung der Deployments - automatisiert und git-basiert.

In der Realität haben wir aber natürlich nur selten ein Environment. Hier kommt nun die nächste ArgoCD Komponente ins Spiel: ApplicationSets.

Skalieren mit ApplicationSets

Nachdem wir unsere Applications auf dev ausgerollt haben, wollen wir uns nun die Umgebungen stage und prod vornehmen. Grundsätzlich ließen sich dafür einzelne Applications definieren. Um Redundanzen bei der Konfiguration zu vermeiden und alles zentral zu steuern, greifen wir jedoch zum ApplicationSet, das wie folgt konfiguriert werden kann:

applicationset.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-env-frontends
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
          - env: stage
          - env: prod
  template:
    metadata:
      name: '{{env}}-frontend'
    spec:
      project: default
      source:
        repoURL: <Repository Link>
        path: <Pfad zum Helm Chart>
        targetRevision: main
        helm:
          valueFiles:
            - values/{{env}}.yaml
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{env}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
---
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-env-backends
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
          - env: stage
          - env: prod
  template:
    metadata:
      name: '{{env}}-backend'
    spec:
      project: default
      source:
        repoURL: <Repository Link>
        path: <Pfad zum Helm Chart>
        targetRevision: main
        helm:
          valueFiles:
            - values/{{env}}.yaml
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{env}}'
      syncPolicy:
        automated:
          prune: true

Auch dieses ApplicationSet können wir in unser Cluster deployen via

kubectl apply -f applicationset.yaml

In diesem Beispiel haben wir nun unsere Applikation auf verschiedenen Umgebungen ausgerollt. Dafür nutzen wir einen `list-Generator, dem wir die Umgebungen explizit als Liste mitgeben.

Alternativ ließen sich git, matrix oder `cluster-basierte Generatoren nutzen, um Applications aus Repositories, Clustern oder Verzeichnisstrukturen dynamisch zu erzeugen. Mehr Details hierzu findet ihr in den ArgoCD Docs.

Einsatz von AppProjects

Nachdem wir nun sowohl die Ressourcen Application und Application Set kennen gelernt haben, wollen wir uns nun noch mit dem dritten Schlüsselkonzept befassen: Dem AppProject.

In den vorangegangenen Konfigurationen haben wir als project immer "default" angegeben. Für unseren ersten Demo-Case ist das natürlich in Ordnung - langfristig lohnt es sich aber, eigene Projekte anzulegen. So lassen sich zentrale Regeln definieren: Welche Repositories sind erlaubt? In welche Namespaces darf deployed werden? Welche Cluster-Zugänge dürfen verwendet werden?

Eine exemplarische Konfiguration eines AppProjects könnte wie folgt aussehen

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: dev
  namespace: argocd
spec:
  description: Projekt für Entwicklungsumgebung
  sourceRepos:
    - <Repository Link(s)> 
  destinations:
    - namespace: dev
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'

Die zugehörigen Applications oder ApplicationSets können diesem Projekt dann entsprechend über `spec.project: dev zugewiesen werden.

Fazit

Wie wir sehen konnten, lassen sich Anwendungen mit ArgoCD strukturiert und wiederholbar in verschiedene Umgebungen deployen. Auch der Zugriff auf private Container-Registries, etwa bei GitLab, lässt sich dabei problemlos einrichten.

Im nächsten Schritt - und damit dem nächsten Artikel dieser Serie - lohnt sich ein Blick auf die Integration von CI/CD-Pipelines und ArgoCD. Hier zeigen wir euch, welche Strategien es gibt, um Deployments nach erfolgreichem Build zu automatisieren und gehen tiefer auf den ArgoCD Image Updater ein.

Blog ArgoCD in der Praxis: Installation, Konfiguration und Application Management