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