homelab-codex-ws/docs/sessions/2026-06-22.md

okf	type	visibility	status	updated	links
0.1	session-log	private	active	2026-06-22

Sesja 2026-06-22 — decyzja: Prometheus jako źródło prawdy dla liveness floty

Cel

Rozstrzygnięcie architektoniczne: czym zastąpić obecną rurę wykrywania liveness floty node-agent → rsync/ssh → observer (warstwa sensoryczno-transportowa będąca przyczyną większości nawracających awarii). Plus precondition infrastrukturalny pod nowy serwis na VPS (swap).

---

DECYZJA: Prometheus (pull, up{}) zastępuje WYKRYWANIE liveness

Co zastępujemy (warstwa sensoryczno-transportowa)

Prometheus pull + metryka up{} przejmuje rolę dotychczasowej rury:

• node-agent jako shipper eventów,
• rsync/ssh transport,
• pliki eventów,
• observer prune/checkpoint,
• egzekwowanie TTL liveness.

To była przyczyna większości nawracających awarii:

• uid 1004 != 1000 — strict ownership check OpenSSH wywalał shipping,
• ślepy ssh-mount (LUSTRO, /root/.ssh vs /home/homelab/.ssh),
• bloat (~242k eventów na VPS),
• race prune ↔ checkpoint w observerze,
• NOMINAL-bez-TTL (martwy node pokazywany jako zdrowy).

Pull eliminuje całą warstwę push: brak kluczy, brak ownership, brak event-store do prune'owania, brak ręcznego TTL — up==0 przez czas for: jest stanem prawdy.

Świadoma granica zakresu — co ZOSTAJE

Prometheus zastępuje wykrywanie, NIE cały system. Nietknięte:

• supervisor — remediacja (container_restart / redeploy),
• observer / panel agents.okit.pl — do przepięcia na źródło Prometheus (OTWARTE, największy znak zapytania przy cutoverze),
• ha-diag-agent — logika domenowa HA (diff system_health, encje unavailable, WS heartbeat) — Prometheus tego nie widzi,
• historia incydentów / lifecycle,
• out-of-band watchdog.

BEZ Alertmanagera — świadoma decyzja

Jeden kanał Telegram (@okitaialerts_bot). Rolę dostarczania przejmuje brain-watchdog: dochodzi mu drugie wejście — odpytanie Prometheus /api/v1/alerts — obok obecnego pingu mózgu. Reguły alertowe z histerezą (for:) po stronie Prometheusa; watchdog pozostaje cienki (odczyt firing + Telegram). Nie wprowadzamy osobnego Alertmanagera, żeby nie mnożyć kanałów ani komponentu do utrzymania.

Uwaga: ta decyzja zastępuje wcześniejszy szkic z sesji 2026-06-17 (blackbox_exporter + Alertmanager). Wybrano pull up{} + watchdog jako tor alertu.

---

Osobny fleet-Prometheus pod GitOps — NIE adopcja domowego instance

Stawiamy osobny Prometheus floty, zarządzany przez GitOps. NIE adoptujemy domowego instance na PIHA.

Powód — domowy prom na PIHA to liability nie wart adopcji:

• LAN-only (scrape 192.168.31.x), mija nody tylko-Tailscale (VPS, chelsty),
• poza repo (/home/pi/monitoring/prometheus.yml, konfigurowany ręcznie),
• bez alertingu (alerting: i rule_files: puste),
• sekrety plaintext w configu (long-lived token HAOS + bearer watchtower — do rotacji).

Adopcja = dziedziczenie liability (migracja, ekstrakcja sekretów) plus blast-radius na działający monitoring bezpieczeństwa domu (crowdsec / fail2ban / haos) za znikomą wygraną. Osobny instance izoluje flotę od domu.

Placement: VPS

• Host: VPS (ubuntu-4gb-hel1-1, 100.95.58.48).
• Out-of-band zachowane: watchdog na PIHA pilnuje VPS z innej maszyny — Prometheus na VPS nie jest sędzią własnej śmierci.
• VPS ma już node_exporter (role: metrics-exporter) = pierwszy target floty gotowy.

---

ZROBIONE w tej sesji

Swap 4 GB na VPS — precondition pod Prometheusa

• /swapfile aktywny i trwały (wpis w /etc/fstab).
• vm.swappiness=10 ustawione na żywo i w /etc/sysctl.conf.
• Weryfikacja: free -h → Swap: 4.0Gi (0B used); /proc/swaps zawiera /swapfile.
• Powód: VPS ma 3.7 GB RAM, wcześniej swap=0 — przyczyna OOM 2026-06-01. Prometheus jest RAM-głodny; swap to bufor bezpieczeństwa.
• ⚠️ To host-level one-off — nie czysto GitOps-owalne, wykonane świadomie gotowcem. Zapisane jako celowy host-state w hosts/vps/host.yaml, żeby przy odtwarzaniu VPS nie zniknęło cicho (wzorzec jak uid/grupy po 8-dniowej awarii).

---

Plan następnych kroków (OTWARTE — NIE realizowane w tej sesji)

Kolejność = priorytet:

1. Scaffold serwisu fleet-prometheus pod GitOps — worktree task/fleet-prometheus, wzorzec services/vikunja/: docker-compose.yml + env.example + service.yaml + README.md + healthcheck.sh. Rejestracja w hosts/vps/services.yaml + inventory/topology.yaml. Exposure: tailscale-internal. Pusty scrape na start (self + lokalny node_exporter VPS).
2. Inwentaryzacja nodów floty 100.x do scrape (osobny krok).
3. Container-layer exporter (cAdvisor lub lekki docker-state) — brakujący klocek; node_exporter nie widzi kontenerów.
4. Reguły liveness (up==0 for: 5m) w Prometheusie.
5. brain-watchdog: drugie wejście — odpyt Prometheus firing → Telegram, bez ruszania działającego toru token → chat_id.
6. Rotacja tokenu HAOS w domowym prom (plaintext).
7. Przepięcie observer / panel agents.okit.pl na Prometheus jako źródło — największy znak zapytania przy cutoverze.
8. Parallel-run obok rury eventowej; cutover dopiero gdy Prometheus-truth się udowodni.

---

Wnioski

• Klasa awarii (push shipping: klucze, ownership, bloat, race, TTL) znika nie przez kolejny fix, lecz przez zmianę modelu transportu na pull — Prometheus widzi martwy target jako up==0, bez warstwy dostarczania do zepsucia.
• Granica zakresu trzymana świadomie: Prometheus = wykrywanie, nie remediacja ani logika domenowa HA. Zastępujemy sensor, nie mózg.
• Osobny instance > adopcja: nie dziedziczy się liability ani blast-radius na monitoring bezpieczeństwa domu dla wygody współdzielenia.
• BEZ Alertmanagera: cienki watchdog z drugim wejściem zamiast nowego komponentu — jeden kanał Telegram pozostaje jeden.
• Swap = precondition, nie cel — odblokowuje RAM-ciasny VPS pod nowy serwis; udokumentowany jako celowy host-state, nie ukryta ręczna zmiana.