Document GitOps drift recovery and InfluxDB LAN access

2026-05-04 15:23:49 +02:00
parent 7268f4ce1e
commit 821fe99807
6 changed files with 181 additions and 4 deletions
@@ -0,0 +1,127 @@
+# 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
+
+```bash
+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:
+
+```bash
+cd /mnt/user/services/stacks/<stack-name>
+git rev-parse --short HEAD
+git status -sb
+```
+
+Bei Drift:
+
+```bash
+git fetch --all --prune
+git reset --hard origin/master
+```
+
+Erst danach deployen.
+
+### 3. Docker Runtime
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+cd /mnt/user/services/stacks/grafana
+git fetch --all --prune
+git reset --hard origin/master
+docker compose --env-file .env -p grafana -f ops/grafana-influxdb/docker-compose.yml up -d --force-recreate --no-deps influxdb3-core
+```
+
+Danach pruefen:
+
+```bash
+docker network ls | grep -E "grafana|influx"
+docker inspect influxdb3-core --format '{{json .NetworkSettings.Networks}}'
+docker inspect 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`.
+- `influxdb3-core` haengt an `grafana_grafana_influx_internal` und `grafana_grafana_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 `grafana_influx_internal` und `grafana_influx_lan`. Durch den Compose-Projektnamen `grafana` werden daraus zur Laufzeit die Docker-Netze `grafana_grafana_influx_internal` und `grafana_grafana_influx_lan`.
+
+## 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.
@@ -16,6 +16,14 @@ Dieses Dokument ist nur noch ein historischer Verlauf. Der aktuelle operative Ab

 ## Historische Meilensteine

+### 2026-05-04 - Home Assistant InfluxDB LAN-Port und Drift-Runbook
+
+- `influxdb3-core` fuer Home-Assistant-Writer auf LAN-Port `8181` vorbereitet und deployed.
+- InfluxDB bleibt ohne Traefik-/Public-Route und haengt nicht im `frontend_net`.
+- Fuer aktives Docker Host-Port-Publishing wurde zusaetzlich zum internen `grafana_influx_internal` das Compose-Netz `grafana_influx_lan` ergaenzt.
+- Komodo Periphery dauerhaft um `/mnt/user/services:/mnt/user/services` und `frontend_net` ergaenzt, damit Stack-Workspaces und Gitea-Zugriff reproduzierbar funktionieren.
+- `docs/GITOPS_DRIFT_RUNBOOK.md` angelegt, um lokale Git-Kopie, Gitea, Komodo Workspace, Docker Runtime und Host-Listener getrennt zu pruefen.
+
 ### 2026-03-28 - GitOps-Konsolidierung

 - Komodo als primaeren Stack-Manager eingefuehrt.
@@ -184,6 +184,22 @@ Wenn Drift erkannt wird, gilt:
   - oder Realitaet an Repo zurueckfuehren
 4. erst danach weiterarbeiten

+### Pflichtcheck bei Drift-Verdacht
+
+Vor jedem Reparaturversuch muessen die Ebenen getrennt geprueft werden:
+
+1. lokaler Clone
+2. Gitea `origin/master`
+3. Komodo Stack Workspace
+4. Docker Runtime
+5. Host-Netzwerklistener
+
+Das detaillierte Runbook steht in `docs/GITOPS_DRIFT_RUNBOOK.md`.
+
+**Regel:** `HostConfig.PortBindings` allein beweist keinen aktiven Host-Port. Entscheidend sind `NetworkSettings.Ports`, `docker ps`, `ss -ltnp` und ein echter `curl` gegen den Host-Port.
+
+**Stop-Regel:** Wenn zwei Reparaturversuche nicht zum erwarteten Ergebnis fuehren, keine weiteren Schreibbefehle ausfuehren. Erst die Pflichtmatrix aus dem Runbook ausfuellen.
+
 ---

 ## Ausnahmefall: Hotfix auf dem Host
@@ -283,6 +299,7 @@ Nach jeder erfolgreichen Migration oder relevanten Aenderung muessen diese Datei
 - `docs/SECRETS_MAP.md`
 - `docs/ROLLBACK.md`
 - `HOMELAB_ARCHITECTURE_MASTER_V2.md` falls Architektur betroffen ist
+- `docs/GITOPS_DRIFT_RUNBOOK.md` falls GitOps-/Komodo-/Runtime-Drift betroffen ist

 ---