homelab/docs/11-gitops-argocd.md

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

ssh-keyscan 192.168.11.182

2. Known Hosts ConfigMap patchen

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)

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-----
    ...

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:

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

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

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

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:

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.

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

kubectl -n pihole delete pod <alter-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:

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)