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
- Username:
admin - Passwort: Output des Befehls
Erst-Login und Passwortwechsel
https://argocd.tech.homeserveröffnen.- Login mit
admin+ Initial-Passwort. - User-Icon oben links anklicken.
- User Info.
- Update Password.
- Neues, starkes Passwort vergeben und bestätigen.
- 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:
- Settings → Repositories
- Connect Repo
- HTTPS oder SSH wählen
- 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:
- ArgoCD scannt die Ordner auf
main; jedes Unterverzeichnis wird zu einer Application. - Application-Name = Ordnername (bei PROD mit Präfix
prod-), Ziel-Namespace = Ordnername. - Das
AppProject(tech/prod) begrenzt Repo und Namespaces, siehe b0020. - ArgoCD synct den Inhalt des Verzeichnisses in den jeweiligen Cluster. Die Ordner sind entweder
plain Manifeste, Kustomize oder ein Helm-Chart (Chart.yaml+values.yaml).
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
- Verzeichnis
argocd/apps/tech/<app-name>/anlegen, Manifeste oder Helm-Chart hineinlegen. <app-name>inargocd_platform_apps(Infrastruktur) oderargocd_workloads_apps(Anwendung)
incapulus-ansible/roles/argocd/defaults/main.ymlergänzen. Sonst fehlt derdestinations-Eintrag im
Projekttech, und der Sync schlägt mit
application destination namespace ... is not permitted in project ...fehl.make render-bootstrap CORE_DIR=<Pfad zu capulus-core>(aktualisiert die committeten Kopien unterargocd/bootstrap/).- Committen, per PR nach
mainbringen (mainist geschützt, siehe
f0090). - Innerhalb von ~3 Minuten erkennt ArgoCD den Ordner, erzeugt die Application und synct sie.
Danachmake argocdlaufen lassen, damit dieargocd-Rolle das Projekttechmit 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
- Verzeichnis
argocd/apps/prod/<app-name>/anlegen. - Namespace in
argocd/bootstrap-prod/appproject.yaml
eintragen und die Datei im Hub anwenden:kubectl apply -f argocd/bootstrap-prod/appproject.yaml. - 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. - Für einen internen Host unter
*.prod.homeserverden Namen indnsmasq_prod_vm_hosts
(capulus-ansible/group_vars/all.yml) aufnehmen undmake dnsmasqausführen, sonst löst der Name auf den
TECH-Cluster auf, siehe c0040. - Per PR nach
main. In der Hub-UI erscheint die Application alsprod-<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:
Synced— Cluster stimmt mit Git übereinOutOfSync— Unterschiede zwischen Git und ClusterUnknown— Status nicht ermittelbar
Health-Status:
Healthy— alle Resources gesundProgressing— Resources deployen/updaten geradeDegraded— Resources schlagen fehlMissing— Resources noch nicht vorhandenSuspended— Resources pausiert (z. B. CronJob)Unknown— Health nicht ermittelbar
Ü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:
- GitHub-Repo → Settings → Webhooks.
- Add webhook.
- 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). - Content type:
application/json. - Just the push event.
- 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.