TL;DR

ArgoCD ist ein GitOps-Controller für Kubernetes, der deinen Cluster automatisch mit einem Git-Repository synchronisiert. In diesem Tutorial installierst du ArgoCD, richtest die CLI ein und deployst eine erste Anwendung — alles mit automatischer Synchronisation und Self-Healing.

ArgoCD installieren und erstes Projekt einrichten

Du willst nicht mehr manuell kubectl apply ausführen, sondern Git als Single Source of Truth nutzen? Dann ist ArgoCD dein Werkzeug. Änderung im Git-Repo gepusht, ArgoCD deployed automatisch.

In diesem Tutorial gehen wir den kompletten Weg: Installation, CLI-Setup, erstes Repository verbinden und eine Anwendung deployen.

Schnellstart: ArgoCD installieren

# Namespace erstellen
kubectl create namespace argocd

# ArgoCD installieren (stable Release)
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Warten bis alle Pods bereit sind
kubectl wait --for=condition=Ready pods --all -n argocd --timeout=300s

Prüfe, was installiert wurde:

kubectl get pods -n argocd

Du solltest diese Komponenten sehen:

Pod	Funktion
argocd-server	API-Server und Web-UI
argocd-repo-server	Klont Git-Repos und rendert Manifeste
argocd-application-controller	Überwacht Cluster-State und synchronisiert
argocd-applicationset-controller	Generiert Applications aus Templates
argocd-redis	Cache für ArgoCD
argocd-dex-server	SSO/OIDC-Integration
argocd-notifications-controller	Benachrichtigungen (Slack, Teams, etc.)

ArgoCD CLI einrichten

Die CLI ist optional, macht aber vieles einfacher als die Web-UI.

# macOS
brew install argocd

# Linux
ARGOCD_VERSION=$(curl -s https://api.github.com/repos/argoproj/argo-cd/releases/latest | grep tag_name | cut -d '"' -f 4)
curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-amd64
chmod +x argocd && sudo mv argocd /usr/local/bin/

Admin-Passwort abrufen und einloggen

# Initiales Admin-Passwort auslesen
ARGOCD_PW=$(kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d)
echo "ArgoCD Password: ${ARGOCD_PW}"

# Port-Forward zum ArgoCD-Server
kubectl port-forward svc/argocd-server -n argocd 8080:443 &

# CLI-Login
argocd login localhost:8080 \
  --username admin \
  --password "${ARGOCD_PW}" \
  --insecure

Ändere als Erstes das Passwort:

argocd account update-password \
  --current-password "${ARGOCD_PW}" \
  --new-password "Dein-Neues-Sicheres-Pw"

Jetzt kannst du auch die Web-UI unter https://localhost:8080 nutzen.

Git-Repository verbinden

ArgoCD muss auf dein Git-Repo zugreifen können. Für öffentliche Repos reicht die URL, für private brauchst du Credentials.

Öffentliches Repository

Kein Setup nötig — ArgoCD kann öffentliche Repos direkt klonen.

Privates Repository (SSH)

# SSH-Key für ArgoCD generieren
ssh-keygen -t ed25519 -f ~/.ssh/argocd-deploy-key -N ""

# Deploy Key in GitHub/GitLab hinzufügen (Read-Only reicht)
cat ~/.ssh/argocd-deploy-key.pub

# Repository in ArgoCD registrieren
argocd repo add git@github.com:dein-org/k8s-manifests.git \
  --ssh-private-key-path ~/.ssh/argocd-deploy-key

Privates Repository (HTTPS + Token)

argocd repo add https://github.com/dein-org/k8s-manifests.git \
  --username git \
  --password ghp_dein-personal-access-token

Prüfe die Verbindung:

argocd repo list

Der Status sollte Successful zeigen.

Erstes Projekt (AppProject) anlegen

ArgoCD organisiert Applications in Projects. Ein Project definiert, welche Repos und Cluster erlaubt sind:

# appproject-team-alpha.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-alpha
  namespace: argocd
spec:
  description: "Projekt für Team Alpha"
  # Erlaubte Git-Repos
  sourceRepos:
    - 'https://github.com/dein-org/k8s-manifests.git'
  # Erlaubte Ziel-Cluster und Namespaces
  destinations:
    - namespace: 'team-alpha-*'
      server: https://kubernetes.default.svc
    - namespace: production
      server: https://kubernetes.default.svc
  # Erlaubte Kubernetes-Ressourcen
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  namespaceResourceWhitelist:
    - group: '*'
      kind: '*'

kubectl apply -f appproject-team-alpha.yaml

Für den Anfang kannst du auch das default-Projekt nutzen, das keine Einschränkungen hat.

Erste Application deployen

Jetzt wird es konkret. Wir deployen eine Nginx-Anwendung aus einem Git-Repository.

Demo-Repository vorbereiten

Erstelle in deinem Git-Repo folgende Struktur:

k8s-manifests/
└── apps/
    └── nginx-demo/
        ├── deployment.yaml
        ├── service.yaml
        └── namespace.yaml

namespace.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: nginx-demo

deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: nginx-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              memory: 128Mi

service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: nginx-demo
spec:
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80

Committe und pushe diese Dateien.

Application in ArgoCD erstellen

Per CLI:

argocd app create nginx-demo \
  --repo https://github.com/dein-org/k8s-manifests.git \
  --path apps/nginx-demo \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace nginx-demo \
  --project default \
  --sync-policy automated \
  --self-heal \
  --auto-prune

Oder deklarativ als YAML (besser für GitOps):

# application-nginx-demo.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/dein-org/k8s-manifests.git
    targetRevision: main
    path: apps/nginx-demo
  destination:
    server: https://kubernetes.default.svc
    namespace: nginx-demo
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

kubectl apply -f application-nginx-demo.yaml

Sync-Status prüfen

# Übersicht aller Applications
argocd app list

# Details einer Application
argocd app get nginx-demo

# Sync manuell auslösen (bei manueller Sync-Policy)
argocd app sync nginx-demo

In der Web-UI siehst du jetzt eine Visualisierung aller Kubernetes-Ressourcen und deren Status.

Auto-Sync und Self-Healing verstehen

Die drei wichtigsten Sync-Optionen:

Option	Beschreibung
`automated`	ArgoCD synchronisiert automatisch, wenn Git-Änderungen erkannt werden
`selfHeal`	Manuelle Änderungen im Cluster (z.B. `kubectl edit`) werden rückgängig gemacht
`prune`	Ressourcen, die aus Git gelöscht werden, werden auch im Cluster gelöscht

Teste Self-Healing:

# Replicas manuell ändern
kubectl scale deployment nginx -n nginx-demo --replicas=5

# Nach wenigen Sekunden: ArgoCD setzt auf 2 zurück
kubectl get deployment nginx -n nginx-demo -w

Helm Charts mit ArgoCD deployen

ArgoCD kann auch Helm Charts direkt deployen:

# application-prometheus.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: monitoring
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://prometheus-community.github.io/helm-charts
    chart: kube-prometheus-stack
    targetRevision: 68.*
    helm:
      values: |
        grafana:
          adminPassword: sicheres-pw
        prometheus:
          prometheusSpec:
            retention: 7d
  destination:
    server: https://kubernetes.default.svc
    namespace: monitoring
  syncPolicy:
    automated:
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

Das ServerSideApply=true ist bei großen Charts wie kube-prometheus-stack wichtig, weil die CRDs sonst die Annotation-Größenlimits sprengen.

Troubleshooting

Application bleibt auf "OutOfSync":

# Diff anzeigen — was unterscheidet sich?
argocd app diff nginx-demo

# Häufige Ursache: Felder, die Kubernetes automatisch setzt
# Lösung: ignoreDifferences in der Application-Spec

"ComparisonError" oder "rpc error":

# Repo-Server-Logs prüfen
kubectl logs -n argocd deployment/argocd-repo-server --tail=50

# Repository-Verbindung testen
argocd repo get https://github.com/dein-org/k8s-manifests.git

FAQ

Wie oft prüft ArgoCD auf Änderungen im Git-Repo?

Standardmäßig alle 3 Minuten. Du kannst das über die ConfigMap argocd-cm mit dem Key timeout.reconciliation anpassen. Alternativ konfiguriere einen Webhook in GitHub/GitLab für sofortige Erkennung.

Kann ArgoCD mehrere Cluster verwalten?

Ja. Füge weitere Cluster mit argocd cluster add CONTEXT-NAME hinzu. ArgoCD deployed dann in jeden registrierten Cluster.

Was ist der Unterschied zwischen Application und ApplicationSet?

Eine Application verwaltet ein Repository/Pfad-Ziel-Paar. Ein ApplicationSet generiert mehrere Applications aus einem Template — z.B. für jeden Namespace oder jeden Cluster automatisch eine Application.

Brauche ich separate Repos für Code und Kubernetes-Manifeste?

Ja, das ist Best Practice. Der Grund: Ein Git-Push im App-Code-Repo triggert die CI-Pipeline (Build, Test, Image). Ein Push im Manifest-Repo triggert das Deployment via ArgoCD. Beides im selben Repo führt zu Endlos-Schleifen.

Nächster Schritt: Sichere deine ArgoCD-Secrets mit Sealed Secrets und richte external-dns ein, damit deine deployten Services automatisch DNS-Einträge bekommen.

ArgoCD installieren und erstes Projekt deployen