PKR-Lab

b0010 - ArgoCD-GitOps-Guide

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/b-kubernetes-gitops/b0010-argocd.md

ArgoCD-GitOps-Guide

Dieses Dokument behandelt ArgoCD-Zugriff, Konfiguration und GitOps-Alltag.

Welche ArgoCD-Instanzen es gibt

Instanz Läuft auf Verwaltet Liest UI
Hub homeserver (TECH, .94) den TECH-Cluster und den PROD-Cluster (dort als Cluster prod registriert) Branch main: argocd/apps/tech/* und argocd/apps/prod/* https://<server-ip>:30443 (HTTPS)
ENTW entw-vm (.100, KVM-VM auf worker-1) nur den ENTW-Cluster Branch entw: argocd/apps/entw/* https://argocd.dev.homeserver

PROD hat keine eigene ArgoCD-Instanz. Im Hub erscheinen PROD-Applications mit dem Präfix prod-
(argocd app list | grep '^prod-'). Die Projekte im Einzelnen: b0020, die
ENTW-Instanz: b0050. Alles Folgende bezieht sich, wenn nicht anders
gesagt, auf den Hub.


Zugriff

Web-UI

Die Web-UI läuft per HTTPS über Traefik (wie alle anderen Dienste, mit dem
internen Zertifikat, siehe d0040):

https://argocd.tech.homeserver

Der Hostname löst über den dnsmasq-Wildcard (*.homeserver) im LAN und im Tailnet auf.
Konfiguriert ist der Ingress in capulus-ansible/roles/argocd (argocd_ingress_enabled,
argocd_ui_host, gesetzt in capulus-ansible/host_vars/homeserver/vars.yml) — als Wert der Rolle,
damit der tägliche Semaphore-Lauf (helm upgrade) ihn nicht zurückdreht.

CLI und CI: Die API läuft über denselben HTTPS-Ingress wie die Web-UI. Der Service
argocd-server ist ClusterIP, es gibt keinen NodePort mehr (Variable
argocd_server_nodeport_enabled, in host_vars/homeserver auf false). Der Server läuft mit
server.insecure: true, TLS endet im Traefik, der letzte Hop bleibt HTTP innerhalb des Nodes.
Die argocd-CLI nutzt --grpc-web, weil Traefik gRPC nicht durchreicht:

argocd login argocd.tech.homeserver --grpc-web

Die Promotion-Kette ruft https://argocd.tech.homeserver und prüft das Zertifikat gegen
pki/homeserver-root-ca.pem. Für das Admin-Passwort
gilt weiter: nur in der Web-UI eingeben, für die CLI ein API-Token verwenden.

Initial-Credentials

Bei der Installation generiert ArgoCD ein zufälliges Initial-Passwort in einem Kubernetes-Secret.

Auslesen:

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

Erst-Login und Passwortwechsel

  1. https://argocd.tech.homeserver öffnen.
  2. Login mit admin + Initial-Passwort.
  3. User-Icon oben links anklicken.
  4. User Info.
  5. Update Password.
  6. Neues, starkes Passwort vergeben und bestätigen.
  7. Save.

Nach dem Passwortwechsel kann das Initial-Secret optional gelöscht werden:

kubectl -n argocd delete secret argocd-initial-admin-secret

Repository-Konfiguration

Das Bootstrap-ApplicationSet ist so konfiguriert, dass es aus dem eigenen
Git-Repo zieht. Bei öffentlichem Repo ist keine zusätzliche Konfiguration nötig.

Privates Repository

Bei privatem Repo Credentials über UI oder CLI hinterlegen:

Über die UI:

  1. Settings → Repositories
  2. Connect Repo
  3. HTTPS oder SSH wählen
  4. Repo-URL und Credentials eingeben

Über die CLI:

# HTTPS mit User/Password oder Token
argocd repo add https://github.com/pkr-lab/capulus-core.git \
  --username YOUR_USER \
  --password YOUR_TOKEN

# SSH mit Key
argocd repo add [email protected]:pkr-lab/capulus-core.git \
  --ssh-private-key-path ~/.ssh/id_rsa

# Repos prüfen
argocd repo list

Über ein Kubernetes-Secret:

apiVersion: v1
kind: Secret
metadata:
  name: home-server-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  type: git
  url: https://github.com/pkr-lab/capulus-core.git
  password: ghp_YOUR_GITHUB_TOKEN
  username: YOUR_USER
kubectl apply -f repo-secret.yaml

ApplicationSet-Struktur

Der Hub kennt drei ApplicationSet-Ressourcen, je Ordner-Familie eine:

ApplicationSet Quelle Projekt Ziel-Cluster Pflege
home-server-apps-tech argocd/apps/tech/* tech Hub-Cluster (TECH) generiert aus bootstrap-applicationset.yaml.j2, committet als argocd/bootstrap/root-applicationset.yaml
home-server-apps-prod explizit gelistete Manifest-Ordner unter argocd/apps/prod/ prod Cluster prod handgeschrieben in argocd/bootstrap-prod/
home-server-apps-prod-charts jeder Ordner mit Chart.yaml unter argocd/apps/prod/ prod Cluster prod dito

Das TECH-Set in Kurzform (Auszug aus der generierten Datei):

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: home-server-apps-tech
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/pkr-lab/capulus-core.git
        revision: main
        directories:
          - path: "argocd/apps/tech/*"
  template:
    metadata:
      name: "{{.path.basename}}"
    spec:
      project: tech            # fest codiert, kein Templating
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{.path.basename}}"
      # ... Sync-Policy, ignoreDifferences, siehe Datei

Funktionsweise:

Verzeichnisstruktur (Auszug, die vollständige Liste steht im
README → Repository-Layout):

argocd/apps/
├── tech/                 → TECH-Cluster (Projekt tech), Infrastruktur + Betriebs-Apps
│   ├── sealed-secrets/   → SealedSecrets-Controller
│   ├── monitoring/       → VictoriaMetrics + Grafana + Alertmanager
│   ├── vaultwarden/      → Passwort-Manager
│   └── ...
├── prod/                 → PROD-Cluster (Projekt prod), Familien-/Vereins-Apps
│   ├── nextcloud/
│   ├── immich/
│   ├── paperless-ngx/
│   └── ...
└── entw/                 → ENTW-Cluster (eigene ArgoCD-Instanz, Branch entw)
    ├── demo-app/
    ├── example-whoami/
    └── sealed-secrets/

Neue Application hinzufügen

Erst entscheiden, in welchem Cluster die App laufen soll: TECH (Infrastruktur, Admin- und
Betriebsdienste), PROD (Apps mit echtem Nutzerkreis: Familie, Verein) oder ENTW (Experimente,
Neuentwicklung). Neue Apps starten in der Regel auf ENTW und wandern über die
Promotion-Kette nach TECH bzw. PROD.

TECH

  1. Verzeichnis argocd/apps/tech/<app-name>/ anlegen, Manifeste oder Helm-Chart hineinlegen.
  2. <app-name> in argocd_platform_apps (Infrastruktur) oder argocd_workloads_apps (Anwendung)
    in capulus-ansible/roles/argocd/defaults/main.yml ergänzen. Sonst fehlt der destinations-Eintrag im
    Projekt tech, und der Sync schlägt mit
    application destination namespace ... is not permitted in project ... fehl.
  3. make render-bootstrap CORE_DIR=<Pfad zu capulus-core> (aktualisiert die committeten Kopien unter argocd/bootstrap/).
  4. Committen, per PR nach main bringen (main ist geschützt, siehe
    f0090).
  5. Innerhalb von ~3 Minuten erkennt ArgoCD den Ordner, erzeugt die Application und synct sie.
    Danach make argocd laufen lassen, damit die argocd-Rolle das Projekt tech mit dem neuen
    Namespace anwendet.

Beispiel mit Plain-Manifest:

mkdir -p argocd/apps/tech/my-app
cat > argocd/apps/tech/my-app/deployment.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: nginx:alpine
          ports:
            - containerPort: 80
EOF

# my-app in argocd_workloads_apps (capulus-ansible/roles/argocd/defaults/main.yml) ergänzen, dann:
make render-bootstrap CORE_DIR=<Pfad zu capulus-core>

git add argocd/apps/tech/my-app/ capulus-ansible/roles/argocd/defaults/main.yml argocd/bootstrap/
git commit -m "feat(apps): add my-app"
git push   # auf einem Feature-Branch, dann PR nach main

Beispiel als Helm-Chart: Ordner argocd/apps/tech/my-helm-app/ mit Chart.yaml, values.yaml und
templates/ anlegen. ArgoCD erkennt die Chart.yaml und behandelt das Verzeichnis als Helm-Chart.

PROD

  1. Verzeichnis argocd/apps/prod/<app-name>/ anlegen.
  2. Namespace in argocd/bootstrap-prod/appproject.yaml
    eintragen und die Datei im Hub anwenden: kubectl apply -f argocd/bootstrap-prod/appproject.yaml.
  3. Nur bei reinen Manifest-Ordnern (ohne Chart.yaml): zusätzlich den Pfad in
    argocd/bootstrap-prod/applicationset.yaml
    ergänzen und anwenden. Helm-Charts werden automatisch gefunden.
  4. Für einen internen Host unter *.prod.homeserver den Namen in dnsmasq_prod_vm_hosts
    (capulus-ansible/group_vars/all.yml) aufnehmen und make dnsmasq ausführen, sonst löst der Name auf den
    TECH-Cluster auf, siehe c0040.
  5. Per PR nach main. In der Hub-UI erscheint die Application als prod-<app-name>.

ENTW

Ordner argocd/apps/entw/<app-name>/ auf dem Branch entw anlegen, fertig. Keine Liste, kein
Projekt, kein Ansible-Lauf. Details: b0050.


Sync-Policies

Das Bootstrap-ApplicationSet konfiguriert Apps mit voller Automation:

syncPolicy:
  automated:
    prune: true      # Resources, die aus Git entfernt wurden, löschen
    selfHeal: true   # Manuelle Änderungen am Cluster zurückdrehen
  syncOptions:
    - CreateNamespace=true    # Ziel-Namespace automatisch erstellen
    - ServerSideApply=true    # Server-Side-Apply für bessere Field-Ownership

Bedeutung:

Policy Effekt
automated ArgoCD synct automatisch bei Git-Changes (kein manueller Sync nötig)
prune: true Aus Git entfernte Resources werden vom Cluster gelöscht
selfHeal: true Manuelle kubectl-Änderungen werden auf den Git-Stand zurückgedreht
CreateNamespace Ziel-Namespace wird erzeugt, falls nicht vorhanden
ServerSideApply Nutzt kubectl apply --server-side für besseres Field-Management

Automated Sync für eine einzelne App deaktivieren:

Für eine App, die manuell kontrolliert werden soll, ein eigenes
Application-Manifest hinterlegen, das die Sync-Policy überschreibt:

# Beispiel: argocd/apps/tech/my-careful-app/argocd-application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-careful-app
  namespace: argocd
  annotations:
    argocd.argoproj.io/skip-reconcile: "true"  # nicht durch das ApplicationSet überschreiben
spec:
  syncPolicy: {}  # nur manueller Sync

CLI-Nutzung

ArgoCD-CLI installieren:

# 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/

# macOS
brew install argocd

Gängige CLI-Kommandos

Authentifizierung:

# Login (--grpc-web: Traefik reicht gRPC nicht durch)
argocd login argocd.tech.homeserver --username admin --password <password> --grpc-web

# ENTW-Instanz
argocd login argocd.dev.homeserver --username admin --password <password> --grpc-web

# Aktueller Context
argocd context

Applications:

# Alle Apps auflisten (PROD-Apps tragen das Präfix prod-)
argocd app list

# Details
argocd app get uptime-kuma

# Manuell syncen
argocd app sync uptime-kuma

# Sync mit Prune (überflüssige Resources entfernen)
argocd app sync uptime-kuma --prune

# Spezifische Resource syncen
argocd app sync uptime-kuma --resource apps:Deployment:uptime-kuma

# Auf Sync warten
argocd app wait uptime-kuma --sync

# Logs
argocd app logs uptime-kuma

# Diff (was würde sich ändern)
argocd app diff uptime-kuma

# Rollback auf vorherige Revision
argocd app rollback uptime-kuma 1   # Revision-Nummer aus der Historie

# Historie
argocd app history uptime-kuma

# App löschen (löscht Default-mäßig KEINE Cluster-Resources)
argocd app delete uptime-kuma

# App UND Cluster-Resources löschen
argocd app delete uptime-kuma --cascade

Repositories:

# Repos auflisten
argocd repo list

# Repo hinzufügen
argocd repo add https://github.com/pkr-lab/capulus-core.git

# Repo entfernen
argocd repo rm https://github.com/pkr-lab/capulus-core.git

Accounts:

# Accounts auflisten
argocd account list

# Passwort ändern
argocd account update-password

# API-Token generieren
argocd account generate-token --account admin

Health-Status

ArgoCD führt zwei Status-Werte pro Application:

Sync-Status:

Health-Status:

Über die UI unter Applications oder per CLI:

argocd app list
# NAME   CLUSTER   NAMESPACE   PROJECT   STATUS   HEALTH   ...

Notifications & Webhooks

GitHub-Webhook (schnellerer Sync)

Default-mäßig pollt ArgoCD das Git-Repo alle 3 Minuten. Mit einem GitHub-Webhook
wird der Sync sofort nach jedem Push ausgelöst:

  1. GitHub-Repo → Settings → Webhooks.
  2. Add webhook.
  3. Payload-URL: https://argocd.tech.homeserver/api/webhook (nur sinnvoll, wenn GitHub den Hub erreichen kann; der Host ist nicht öffentlich, es bleibt beim Polling).
  4. Content type: application/json.
  5. Just the push event.
  6. Add webhook.

Hinweis: Der Server muss aus den GitHub-Servern erreichbar sein. Über Tailscale
geht das nur, wenn er als
Tailscale-Exit-Node eingerichtet oder Subnet-Routing
konfiguriert ist.

Alternativ ist der 3-Minuten-Poll für einen Home-Server völlig ausreichend.


Fehlersuche

Es gibt zwei ArgoCD-Instanzen: den Hub auf TECH (für TECH und PROD) und die isolierte Instanz auf ENTW (Instanzen). Schnellster Einstieg ohne Login ist kubectl, auf den Cluster mit dem Hub:

kubectl -n argocd get applications.argoproj.io
kubectl -n argocd get applicationsets.argoproj.io
kubectl -n argocd describe application <name>           # Conditions und Operation-Meldung
kubectl -n argocd logs deploy/argocd-application-controller --tail=100
kubectl -n argocd logs deploy/argocd-repo-server --tail=100
kubectl -n argocd logs deploy/argocd-applicationset-controller --tail=100

Mit cubi (cubi argocd) sieht man dieselben Daten als Tabelle, inklusive Problem-Filter, Diff und Refresh.

Symptom Ursache Lösung
Neue App erscheint nicht in ArgoCD ApplicationSet findet den Ordner nicht (falscher Pfad, Branch, nicht gepusht), Namespace nicht im AppProject, Generator-Fehler (missingkey=error) kubectl -n argocd describe applicationset home-server-apps-tech, Ordner argocd/apps/<cluster>/<app>/ prüfen, AppProjects, Neue-App-Ablauf oben
App OutOfSync, Sync meldet Erfolg und bleibt OutOfSync Controller ändert Felder (HPA setzt replicas, Operator ergänzt Felder) ignoreDifferences im ApplicationSet, HPA, argocd app diff <name>
App Unknown / ComparisonError Helm-Rendering oder Manifest fehlerhaft, Repo nicht erreichbar kubectl -n argocd describe application <name> (Conditions), repo-server-Log, lokal helm template argocd/apps/<cluster>/<app>
Sync-Fehler project … is not permitted to deploy to namespace … Namespace fehlt im AppProject Liste argocd_platform_apps / argocd_workloads_apps bzw. argocd/bootstrap-prod/appproject.yaml ergänzen, AppProjects
Sync-Fehler resource … is not permitted in project … clusterweiter Ressourcentyp fehlt in clusterResourceWhitelist (PROD) Typ im Projekt prod ergänzen
Sync-Fehler one or more objects failed to apply mit Invalid value Schemafehler in den Manifesten kubectl apply --dry-run=server bzw. CI-Job kubeconform (f0070)
App Progressing bleibt hängen Pod startet nicht Kubernetes bzw. kubectl -n <ns> describe pod, Logs
App Degraded Ressource unhealthy (Deployment ohne verfügbare Replikas, Job fehlgeschlagen) betroffene Ressource in der Application-Detailansicht
SealedSecret-App dauerhaft OutOfSync /status des SealedSecret im ApplicationSet per ignoreDifferences ausgenommen. Fehlt der Eintrag, ergänzen
App wird sofort wieder auf Git zurückgesetzt selfHeal: true gewollt. Für Tests Auto-Sync abschalten (cubi autosync)
argocd login scheitert mit connection reset/gRPC-Fehlern Traefik reicht gRPC nicht durch --grpc-web verwenden (CLI-Nutzung)
argocd-Befehl: Unauthenticated / token is expired Login abgelaufen cubi login oder argocd login, Login
Webhook löst keinen sofortigen Sync aus Webhook nicht eingerichtet, Secret falsch Notifications & Webhooks; ohne Webhook dauert der Abgleich etwa 3 Minuten
repository not found / Authentifizierungsfehler beim Repo Zugangsdaten abgelaufen Repo-Credentials erneuern (Repository-Konfiguration), Token-Register
PROD-Apps fehlen ApplicationSets home-server-apps-prod/-prod-charts, Cluster prod im Hub nicht registriert oder nicht erreichbar kubectl -n argocd get secret -l argocd.argoproj.io/secret-type=cluster, bootstrap-prod
Admin-Passwort unbekannt Initial-Secret wurde gelöscht oder Passwort geändert Initial-Credentials, Passwort zurücksetzen über das Secret argocd-secret

Der Ablauf von Promotion und CI-Token: f00b0. Allgemeine Fehlersuche: zentrale Fehlersuche.