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

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

```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)