From 441a5f6bb09acf0cbacbf4e1b86c45e2671c7c78 Mon Sep 17 00:00:00 2001 From: mtkadmin Date: Fri, 20 Mar 2026 00:58:47 +0000 Subject: [PATCH] docs: add GitOps/ArgoCD setup documentation (11-gitops-argocd.md) Documents SSH auth, ArgoCD Applications, known-hosts setup, kustomization fixes and troubleshooting for RWO/Multi-Attach issues. Co-Authored-By: Claude Sonnet 4.6 --- docs/11-gitops-argocd.md | 238 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 docs/11-gitops-argocd.md diff --git a/docs/11-gitops-argocd.md b/docs/11-gitops-argocd.md new file mode 100644 index 0000000..10b9b3e --- /dev/null +++ b/docs/11-gitops-argocd.md @@ -0,0 +1,238 @@ +# 11 · GitOps Setup mit ArgoCD + Gitea + +**Datum:** 2026-03-20 + +--- + +## Was wurde eingerichtet + +- Alle Homelab-Manifeste nach Gitea gepusht (`admin/homelab`) +- ArgoCD SSH-Zugang zu Gitea konfiguriert (Deploy Key + Known Hosts) +- ArgoCD Applications für alle k8s-Workloads angelegt +- `.gitignore` für Secrets gesetzt +- kustomization.yaml Dateien bereinigt (secret.yaml entfernt) + +--- + +## Repository-Struktur + +``` +git@192.168.11.182:/admin/homelab.git (SSH) +http://gitea.192.168.11.180.nip.io/admin/homelab (Web) + +~/homelab/ + k8s/ + metallb/ → ArgoCD App: metallb-config + pihole/ → ArgoCD App: pihole + gitea/ → ArgoCD App: gitea + argocd/ → ArgoCD selbst (manuell gemanagt) + omada-mcp/ → kein ArgoCD App (noch) + docs/ + .gitignore → **/secret.yaml, *.key, *.pem +``` + +--- + +## ArgoCD SSH-Zugang zu Gitea + +### 1. Host Keys erfassen + +```bash +ssh-keyscan 192.168.11.182 +``` + +### 2. Known Hosts ConfigMap patchen + +```bash +kubectl -n argocd edit configmap argocd-ssh-known-hosts-cm +``` + +Folgende Zeilen unter `ssh_known_hosts` eintragen: +``` +192.168.11.182 ssh-rsa AAAA... +192.168.11.182 ecdsa-sha2-nistp256 AAAA... +192.168.11.182 ssh-ed25519 AAAA... +``` + +### 3. Deploy Key in ArgoCD (Repo Secret) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: gitea-homelab-repo + namespace: argocd + labels: + argocd.argoproj.io/secret-type: repository +stringData: + type: git + url: ssh://git@192.168.11.182/admin/homelab.git + sshPrivateKey: | + -----BEGIN OPENSSH PRIVATE KEY----- + ... +``` + +```bash +kubectl apply -f gitea-homelab-repo-secret.yaml +``` + +### 4. Deploy Public Key in Gitea hinterlegen + +Gitea → Admin → Settings → SSH Keys → neuen Key eintragen. + +Oder via API: +```bash +curl -X POST http://gitea.192.168.11.180.nip.io/api/v1/user/keys \ + -u admin:PASSWORD \ + -H "Content-Type: application/json" \ + -d '{"key": "ssh-ed25519 AAAA...", "read_only": false, "title": "argocd"}' +``` + +--- + +## ArgoCD Applications + +### pihole + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: pihole + namespace: argocd +spec: + project: default + source: + repoURL: ssh://git@192.168.11.182/admin/homelab.git + targetRevision: master + path: k8s/pihole + destination: + server: https://kubernetes.default.svc + namespace: pihole + syncPolicy: + syncOptions: + - CreateNamespace=true +``` + +### gitea + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: gitea + namespace: argocd +spec: + project: default + source: + repoURL: ssh://git@192.168.11.182/admin/homelab.git + targetRevision: master + path: k8s/gitea + destination: + server: https://kubernetes.default.svc + namespace: gitea + syncPolicy: + syncOptions: + - CreateNamespace=true +``` + +### metallb-config + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: metallb-config + namespace: argocd +spec: + project: default + source: + repoURL: ssh://git@192.168.11.182/admin/homelab.git + targetRevision: master + path: k8s/metallb + destination: + server: https://kubernetes.default.svc + namespace: metallb-system +``` + +--- + +## Troubleshooting + +### Problem: ArgoCD `app path does not exist` + +**Ursache:** Gitea initialisiert mit `main` Branch, Content ist auf `master`. + +**Fix:** In Gitea unter Settings → Default Branch auf `master` setzen. `main` Branch löschen: +```bash +curl -X DELETE http://gitea.../api/v1/repos/admin/homelab/branches/main -u admin:PASS +``` + +### Problem: ArgoCD `knownhosts: key is unknown` + +**Ursache:** Gitea SSH Host Key nicht in ArgoCD known hosts. + +**Fix:** `ssh-keyscan 192.168.11.182` → Output in `argocd-ssh-known-hosts-cm` eintragen. + +### Problem: kustomize build failed — `secret.yaml: no such file or directory` + +**Ursache:** `secret.yaml` ist in `.gitignore` und daher nicht im Repo, aber noch in `kustomization.yaml` referenziert. + +**Fix:** `secret.yaml` aus allen `kustomization.yaml` entfernen. Secrets werden direkt in-cluster verwaltet und nicht über GitOps deployed. + +```bash +# Prüfen ob secret.yaml irgendwo referenziert ist +grep -r "secret\.yaml" k8s/*/kustomization.yaml +``` + +### Problem: RWO Multi-Attach bei ArgoCD Sync + +**Ursache:** ArgoCD deployed neuen Pod auf anderem Node, RWO-Volume bereits attached. + +**Fix 1 (dauerhaft):** `nodeSelector` in Deployment setzen. + +**Fix 2 (einmalig):** Alten Pod manuell löschen damit Volume freigegeben wird: +```bash +kubectl -n pihole delete pod +``` + +--- + +## Gitea SSH-Key für rnk-cp01 + +Damit `git push` von rnk-cp01 funktioniert muss der SSH Public Key des Users in Gitea hinterlegt sein: + +```bash +cat ~/.ssh/id_ed25519.pub +# → Key in Gitea unter User Settings → SSH Keys eintragen + +# Test: +ssh -T git@192.168.11.182 +# → Hi there, admin! You've successfully authenticated... +``` + +--- + +## Endstatus + +| App | Sync | Health | Node | +|---|---|---|---| +| pihole | Synced | Healthy | rnk-wrk01 | +| gitea | Synced | Healthy | rnk-wrk01 | +| metallb-config | Synced | Healthy | — | + +``` +NAME SYNC STATUS HEALTH STATUS +gitea Synced Healthy +metallb-config Synced Healthy +pihole Synced Healthy +``` + +--- + +## Nächste Schritte + +- `syncPolicy.automated` aktivieren für vollautomatisches GitOps +- omada-mcp ArgoCD Application anlegen +- Secrets-Management: Sealed Secrets oder External Secrets Operator evaluieren +- Backup der Gitea-Daten (Longhorn Snapshot Policy)