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 <noreply@anthropic.com>
This commit is contained in:
238
docs/11-gitops-argocd.md
Normal file
238
docs/11-gitops-argocd.md
Normal file
@@ -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 <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)
|
||||||
Reference in New Issue
Block a user