homelab-infra/docs/GITOPS_DRIFT_RUNBOOK.md

GitOps Drift Runbook

Dieses Runbook ist fuer Faelle, in denen Gitea, lokaler Clone, Komodo Workspace und Docker Runtime nicht sichtbar denselben Stand haben.

Ziel

Vor jeder Reparatur muss klar sein, welche Ebene vom Sollzustand abweicht:

1. Lokaler Clone
2. Gitea origin/master
3. Komodo Stack Workspace auf dem Host
4. Laufender Docker-Container
5. Host-Netzwerklistener

Nicht mehrere Ebenen gleichzeitig reparieren. Erst messen, dann genau eine Abweichung beheben.

Pflichtmatrix

1. Lokaler Clone

git status -sb
git rev-parse HEAD
git rev-parse origin/master
git ls-remote https://git.kaleschke.info/Micha/homelab-infra.git refs/heads/master

Alle Hashes muessen gleich sein, bevor Komodo oder Runtime bewertet werden.

2. Komodo Workspace

Auf dem Unraid-Host im Stack-Workspace:

cd /mnt/user/services/stacks/<stack-name>
git rev-parse --short HEAD
git status -sb

Bei Drift:

git fetch --all --prune
git reset --hard origin/master

Erst danach deployen.

3. Docker Runtime

docker inspect <container> --format '{{.Created}}'
docker inspect <container> --format '{{json .NetworkSettings.Networks}}'
docker inspect <container> --format '{{json .NetworkSettings.Ports}}'
docker inspect <container> --format '{{json .HostConfig.PortBindings}}'
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | grep <container-or-service>

Wichtig: HostConfig.PortBindings ist nur die Container-Spezifikation. Entscheidend fuer einen aktiven Host-Port sind NetworkSettings.Ports, docker ps und ein echter Listener.

4. Host-Port / Listener

ss -ltnp | grep <port>
curl -i --max-time 5 http://<host-ip>:<port>/

Ein 401 Unauthorized ist bei geschuetzten APIs oft ein Erfolg: Dienst ist erreichbar, Auth fehlt nur beim Testrequest.

Komodo/Periphery Checks

Wenn Komodo Stacks nicht aus Gitea deployen kann:

docker inspect komodo-periphery --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
docker inspect komodo-periphery --format '{{range $k,$v := .NetworkSettings.Networks}}{{println $k}}{{end}}'
docker exec komodo-periphery sh -lc 'getent hosts git.kaleschke.info'
docker exec komodo-periphery sh -lc 'wget -S -O- -T 5 --no-check-certificate https://git.kaleschke.info 2>&1 | head -40'

Sollzustand:

• /mnt/user/services -> /mnt/user/services ist gemountet.
• komodo_net und frontend_net sind verbunden.
• git.kaleschke.info loest auf 192.168.178.58 auf.
• HTTPS zu Gitea antwortet.

InfluxDB LAN-Port Beispiel

Soll fuer Home Assistant:

cd /mnt/user/services/stacks/monitoring
git fetch --all --prune
git reset --hard origin/master
docker compose --env-file .env -p monitoring -f monitoring/docker-compose.yml up -d --force-recreate --no-deps influxdb3-core

Danach pruefen:

docker network ls | grep -E "monitoring|influx"
docker inspect monitoring-influxdb3-core --format '{{json .NetworkSettings.Networks}}'
docker inspect monitoring-influxdb3-core --format '{{json .NetworkSettings.Ports}}'
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | grep influx
ss -ltnp | grep 8181
curl -i --max-time 5 http://192.168.178.58:8181/

Erwartung:

• Komodo Workspace HEAD entspricht origin/master.
• monitoring-influxdb3-core haengt an monitoring_monitoring_net und monitoring_monitoring_influx_lan.
• Docker zeigt 192.168.178.58:8181->8181/tcp.
• ss zeigt docker-proxy auf 192.168.178.58:8181.
• curl bekommt 401 Unauthorized von InfluxDB.

Hinweis: Im Compose-File heissen die Netze monitoring_net und monitoring_influx_lan. Durch den Compose-Projektnamen monitoring koennen daraus zur Laufzeit Docker-Netze mit Projektpraefix werden.

Stop-Regel

Wenn zwei Reparaturversuche nicht zum erwarteten Ergebnis fuehren:

1. Keine weiteren Schreibbefehle.
2. Pflichtmatrix ausfuellen.
3. Genau eine abweichende Ebene benennen.
4. Erst danach einen neuen Fix ausfuehren.