Files
infrastructure/docs/platform/llm-server/monitoring/GNMON-001-PLAN_Architecture.md
T
spektr bf0ec37fc1 GNMON-001 M6: OIDC-faehiges Dashboard v0.2.0 (App + Rolle + Doku)
App (Ghostnet.Dashboard, baut fehlerfrei mit 0 Warnungen, .NET 10):
- OIDC konfigurationsgetrieben (Auth:Enabled/Authority/ClientId in
  appsettings.json, Secret nur via ENV Auth__ClientSecret), Authorization
  Code Flow mit PKCE, Cookie-Schema
- KeycloakRealmRolesClaimTransformation mappt realm_access.roles auf
  Role-Claims; Policy DashboardAccess erfordert Realm-Rolle
  dashboard-admin (im Off-Modus permissive)
- Endpoint-Autorisierung an MapRazorComponents().RequireAuthorization()
  (.NET 10: AuthorizeRouteView hat keinen Policy-Parameter mehr),
  UseForwardedHeaders fuer TLS-Terminierung an NPM, /login + /logout
- Paket Microsoft.AspNetCore.Authentication.OpenIdConnect 10.0.14

Rolle/Quadlet: host-lokale, verwaltete Secrets-Datei
/etc/gnmon/dashboard-secrets.env (Owner gn-dashboard, 0640, force: false)
per EnvironmentFile im Quadlet; Image-Default auf v0.2.0 angehoben,
Inventory pinnt v0.2.0; Duplikat gnmon_dashboard_quadlet_dir entfernt;
Containerfile-Kommentar an die keep-id-Entscheidung (GNMON-000 M5) angepasst.

Doku: GNMON-000 (M6-Abschnitt, Verifikation 09.11.2026 nach Host-Neustart,
CT-103-Ansible-Nachbau als erledigt markiert) und GNMON-001 v2.1
(Umsetzungsabweichungen: gn-monitor=986, Braille statt ApexCharts,
Hostname mon.ghostnet.selfhost.eu, offene Punkte 1-4 entschieden).

Externe Freigabe (NPM-Proxyhost + Keycloak-Client gn-dashboard +
Auth__Enabled=true) bleibt Betreiber-Schritt, siehe GNMON-000 M6.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-09 05:40:47 +01:00

13 KiB
Raw Blame History

Monitoring

Dokumenten-ID: GNMON-001-PLAN Titel: Host-Monitoring auf dem KI-Server: Systemmetriken, Log-Pipeline und Blazor-Dashboard Stand: 2026-11-09 Status: Revidierter Plan (v2.0) nach Betreiberentscheidungen vom 03.11.2026; M1–M5 produktiv umgesetzt (belegter Stand in GNMON-000), M6 externe Freigabe in Vorbereitung Referenzen: GNENC-001, GNENC-002, GNAI-005, GNAI-006

Änderungsverlauf

Datum Version Autor Beschreibung
19.10.2026 1.0 Betreiber Planungsabschluss: Metrics-Collector (system.json) + Flask-Dashboard
03.11.2026 2.0 Betreiber / Mistral Vibe Revision: Dashboard auf ASP.NET Core Blazor Server; Metriken über VictoriaMetrics + Exporter statt system.json-Schnappschuss; neue Log-Pipeline (Alloy + Loki) für journald-, Container- und Encoding-Logs
09.11.2026 2.1 Mistral Vibe Umsetzungsabweichungen gegenüber v2.0 nachgeführt (belegter Stand in GNMON-000): gn-monitor hat UID/GID 986 (die geplante 983 war an gn-download vergeben), Charts als eigene Braille-Komponente statt ApexCharts, NPM-Hostname mon.ghostnet.selfhost.eu entschieden; M1–M5 sind produktiv auf dem KI-Server (System-Scope) und der Workstation (User-Scope) ausgerollt

Änderungen gegenüber v1.0

  1. Dashboard-Technik: Python/Flask → ASP.NET Core Blazor Server (.NET 10 LTS), C#. Betreiberentscheidung 03.11.2026; löst die Festlegung aus v1.0 ab.
  2. Metrikpfad: Der host-seitige Metrics-Collector mit state/system.json (10-s-Schnappschuss, keine Historie) entfällt. Ersetzt durch node_exporter mit AMD-GPU-Textfile-Skript und VictoriaMetrics als Zeitreihen-Store. Damit sind Verläufe (24 h / 7 d / 30 d) möglich.
  3. Neu: Log-Pipeline. v1.0 hatte keine Log-Anzeige. Neu: Grafana Alloy (host-seitig) → Loki für journald-, Podman-Container- und Encoding-Job-Logs.
  4. Workload-Status unverändert: Das Filesystem-Handover für Encoding (state/jobs/*.json, read-only Mount) bleibt wie in v1.0 bzw. GNENC-002.
  5. Neues Konto gn-monitor für die Datenhaltung (VictoriaMetrics, Loki); gn-dashboard (984) bleibt auf die Web-App beschränkt.

1. Zweck und Abgrenzung

Host-weites Monitoring für ghostnet-ki (10.0.0.90) mit drei Datenpfaden:

  • Zeitreihen (CPU, RAM, Disk inkl. NFS-Export, GPU-Util, VRAM, Temperatur/Power) über VictoriaMetrics,
  • Logs (journald, Podman-Container-Logs, Encoding-Job-Logs) über Loki,
  • Workload-Zustände (Encoding-Jobs) über read-only Dateizugriff.

Später erweiterbar um LLM-Metriken (GPU-Util unter Inferenz, Serving-Statistik) — eigenes Thema im AI-Bereich. Der Bereich bleibt fachlich getrennt vom Encoding-Workload.

Bewusste Abgrenzung: Grafana/OpenSearch kommen nicht zum Einsatz. Ziel ist ein einziges, selbst erweiterbares Dashboard in einem Stack; VictoriaMetrics und Loki behalten dennoch ihre Standard-HTTP-APIs, sodass ein späteres Grafana zum Debuggen jederzeit andockbar wäre, ohne die Architektur zu ändern.

2. Architektur

flowchart LR
  Browser["Browser (LAN / WireGuard)"] --> NPM["NPM CT-103 (TLS)"]
  NPM --> KC["Keycloak CT-102 (OIDC, MFA)"]
  NPM --> DB["Blazor-Dashboard, gn-dashboard (984), 10.0.0.90:8080"]
  DB -->|"PromQL, 10.0.0.90:8428"| VM["VictoriaMetrics, gn-monitor (986)"]
  DB -->|"LogQL, 10.0.0.90:3100"| LK["Loki, gn-monitor (986)"]
  DB -->|"read-only Mount"| ST["Encoding state/jobs"]
  subgraph HOST["Host-systemd auf ghostnet-ki"]
    NE["node_exporter (9100) mit AMD-Textfile-Skript"]
    AL["Grafana Alloy: journald + Job-Logfiles"]
  end
  NE --> VM
  AL --> LK

Architekturprinzip: Die Dashboard-App bleibt eine read-only, GPU-lose Einheit ohne Schreibzugriff auf Pipeline oder Host. Historie und Log-Aggregation liegen in zwei dedizierten, rootless betriebenen Diensten; die App fragt deren HTTP-APIs ab.

3. Komponenten

Komponente Konto / Betrieb Aufgabe Laufzeit
node_exporter Host-systemd, Metrics-Account (siehe Abschnitt 9, offener Punkt 1) CPU, RAM, Disk (Root + NFS-Export), Load; liest Textfile-Verzeichnis dauerhaft
AMD-GPU-Textfile-Skript Host-systemd-Timer (10 s) liest rocm-smi/sysfs (Util, VRAM, Junction-Temp, Power je Karte); schreibt .prom-Textfile atomar für node_exporter dauerhaft
Grafana Alloy Host-systemd, Metrics-Account, Gruppen systemd-journal + gn-media liest journald (System + Container) und Encoding-Logfiles; pusht nach Loki dauerhaft
VictoriaMetrics (single) gn-monitor (986), rootless Quadlet scrapet node_exporter (10 s); speichert Zeitreihen; /api/v1/query + query_range (Prometheus-API-kompatibel) dauerhaft
Loki gn-monitor (986), rootless Quadlet Log-Aggregation; /loki/api/v1/query_range; Filesystem-Store, kein S3 dauerhaft
Blazor-Dashboard gn-dashboard (984), rootless Quadlet UI: Ressourcen-Charts, GPU-Detail, Encoding-Übersicht, Log-Browser; Keycloak-OIDC dauerhaft

Entscheidungen mit Begründung:

  • VictoriaMetrics statt Prometheus: ein einzelnes, statisches Binary, deutlich geringerer RAM-Bedarf, integrierter Scrape (-promscrape.config), Prometheus-Query-API-kompatibel. Ein späterer Wechsel zu Prometheus wäre für das Dashboard transparent.
  • Loki statt OpenSearch: Single-Binary, kein JVM-Cluster, indexiert nur Labels — passend zu Single-Host-Betrieb ohne HA-Aussage (vgl. GNAI-001).
  • Alloy statt Promtail: Promtail ist eingefroren; Alloy ist der offizielle Nachfolger und liest journald nativ (loki.source.journal) sowie Dateien (local.file_match + loki.source.file).
  • AMD-GPU-Metriken als eigenes Textfile-Skript statt fremdem Exporter: Abhängigkeitsfrei, identische Quelle (rocm-smi/sysfs) wie bereits 2026-11-01 beim thermischen Lastprofil verwendet; Skript liegt versioniert im Repo (Abschnitt 8).

4. Metrikpfad

  • Scrape: VictoriaMetrics → node_exporter auf 10.0.0.90:9100, Intervall 10 s.
  • GPU: Das Textfile-Skript schreibt pro Karte Metriken wie gn_gpu_utilization_percent{card="0"}, gn_gpu_vram_used_bytes, gn_gpu_junction_temp_celsius, gn_gpu_power_watts — Werte aus rocm-smi bzw. /sys/class/drm/card*/device/gpu_metrics. Modus 0644, atomarer Schreibwechsel (.tmp + rename).
  • Disk: node_exporter erfasst Root-Dateisystem und den gemounteten NFS-Export (CT-101) über die Host-Mount-Tabelle.
  • Retention: -retentionPeriod=60d (Startwert; Anpassung nach erstem Realbetrieb).
  • Zugriff: Port 8428 (VM) und 9100 (node_exporter) nur host-lokal bzw. aus dem Dashboard-Container; nftables-Regeln siehe Abschnitt 7.

5. Logpfad

  • System-/Dienst-Logs: Alloy liest journald über die Mitgliedschaft systemd-journal; Labels mindestens unit, priority, hostname.
  • Podman-Container-Logs: Die Workload-Quadlets (Encoding, später LLM) setzen log_driver=journald, damit Container-Logs einheitlich im Journal landen und dort _UID des jeweiligen Workload-Kontos sowie CONTAINER_NAME als Labels nutzbar sind. Rootless-Stores fremder Konten werden nicht gelesen.
  • Encoding-Job-Logs: Alloy verfolgt die Logdateien der Pipeline (read-only über gn-media); Label job aus dem Dateinamen/Pfad.
  • Retention: Loki Filesystem-Store, retention_period: 30d (Startwert), Compactor aktiv.
  • Zugriff: Port 3100 (Loki) nur host-lokal bzw. Dashboard-Container.

6. Dashboard (Blazor Server)

  • Technik: ASP.NET Core Blazor Web App, Render Mode Interactive Server, .NET 10 (LTS). Ein Projekt, keine separate API; WebSocket-Upgrade in NPM aktivieren.
  • Views:
    1. Ressourcen: Live-Werte + Verlaufscharts (1 h / 24 h / 7 t) für CPU, RAM, Disk je Mount.
    2. GPU-Detail: je RX 6900 XT Util, VRAM, Junction-Temp, Power — Live + Verlauf.
    3. Encoding: aktive Jobs mit Fortschritt, Queue-Tiefe pro Profil, Historie done/failed (30 Tage), Fehlerfälle mit Ablageort output/_failed/ — aus state/jobs/*.json (read-only Mount, unverändert zu v1.0).
    4. Logs: Browser über Loki query_range mit Filter unit/container/job und Live-Tail (Polling alle 2 s).
  • Charts: Blazor-ApexCharts umgesetzt: eigene Braille-Chart-Komponente ohne JS-Chart-Bibliothek (Betreiberentscheidung 04.11.2026, GNMON-000 M3.4); ApexCharts inkl. CDN-Referenz wurde entfernt.
  • Live-Updates: server-seitige Timer/Streaming-Rendering für Live-Kacheln; keine Client-seitige Logik außer der Chart-Rendering-Bibliothek.
  • Image: llm-server/monitoring/images/dashboard/Containerfile, Base mcr.microsoft.com/dotnet/aspnet:10.x, Digest gepinnt, Non-Root-User im Image (gemappte UID 984).

7. Authentifizierung und Erreichbarkeit

  • Ingress: NPM (CT-103) mit TLS und Split-DNS-Name (Hostname offen, Punkt 2); Proxy auf 10.0.0.90:8080, WebSocket-Upgrade erforderlich. Hostname folgt dem Muster der bestehenden Admin-Pfade (GNAI-005/GNAI-006).
  • OIDC: Die App authentifiziert selbst über Microsoft.AspNetCore.Authentication.OpenIdConnect mit PKCE (Confidential Client gn-dashboard in Keycloak CT-102) — analog zum bestätigten Vaultwarden-OIDC-Muster. Rollen-Claim (Realm-Rolle dashboard-admin) für die Autorisierung; MFA wird über die Keycloak-Realm-Policy erzwungen, nicht in der App.
  • Forwarded Headers: ForwardedHeaders-Middleware, da TLS an NPM endet.
  • Netzwerksegmentierung (host-nftables auf ghostnet-ki):
    • 8080 (Dashboard) → erlaubt von 10.0.0.10 (NPM),
    • 8428, 9100, 3100 → nur host-lokal / aus den rootless Containern desselben Hosts; per Regel von LAN und WireGuard abweisbar testen.
  • Rootless-Besonderheit: Die Quadlets laufen unter verschiedenen Konten mit getrennten Netz-Namespaces; Quartett-übergreifender Verkehr läuft über die an die Host-IP gebundenen Ports (PublishPort, unprivilegiert >1024). Das ist der Grund für die nftables-Regeln oben; Abnahme mit Positiv-/Negativtest.

8. Repository-Grenzen

llm-server/monitoring/
├── ansible/       # Playbooks + Rollen: Konten, systemd-Units, Quadlet-Rollen, nftables
├── images/
│   └── dashboard/ # Containerfile (Blazor-App), Digest-Pin
├── scripts/
│   ├── amdgpu-textfile-collector.py (o. ä.)
│   └── scrape.yml # VictoriaMetrics-Promscrape-Konfig
└── src/
    └── Ghostnet.Dashboard/  # Blazor-Projekt (später ggf. Solution mit Tests)

VictoriaMetrics und Loki laufen mit gepinnten Upstream-Images (kein Eigenbau-Image nötig); Loki-/VM-Konfiguration liegt versioniert unter ansible/ (Rollen) bzw. images/.

9. Offene Punkte

  1. Metrics-Account-Identität — entschieden/umgesetzt: dedizierter Account gn-monitor, UID/GID 986 mit systemd-journal-Gruppe (05.11.2026, GNMON-000 M5; die ursprünglich geplante 983 war auf dem Server an gn-download vergeben).
  2. NPM-Hostname und Keycloak-Client gn-dashboard — Hostname entschieden: mon.ghostnet.selfhost.eu (06.11.2026); Keycloak-Client und NPM-Proxy-Host folgen mit den M6-Betreiber-Schritten (GNMON-000).
  3. UID/GID für gn-monitor — erledigt: 986 (siehe Punkt 1).
  4. Chart-Bibliothek — entschieden: eigene Braille-Komponente statt ApexCharts (04.11.2026, Abschnitt 6).
  5. LLM-Metriken (später, eigenes Thema im AI-Bereich): teilweise umgesetzt — gn_ai_active_env{env} aus der ai_environment_switch-Rolle plus Regel GnAiEnvironmentDown (GNMON-000 M5); Tokens/Latenzen der Inference-Engine bleiben offen.
  6. Retention-Feinjustierung (60 d Metriken / 30 d Logs) nach erstem Realbetriebsmonat — offen.

10. Abnahmekriterien (Auszug für die Umsetzung)

  • Ansible-Rollen idempotent: zweiter Lauf changed=0, failed=0 (Konvention des Host-Projekts).
  • Dashboard zeigt Live-Metriken und 24-h-Verläufe für CPU, RAM, Disk, beide GPUs.
  • Logs aller drei Quellen (journald, Podman-Container, Encoding-Jobs) im Log-Browser auffindbar; Container-Log eines gestoppten/gestarteten Testcontainers erscheint/verschwindet korrekt.
  • Login ohne Keycloak-Session abgewiesen; mit Realm-Rolle dashboard-admin und MFA erfolgreich; ohne Rolle abgewiesen (Negativtest).
  • nftables-Negativtest: 8428/9100/3100 aus LAN nicht erreichbar; 8080 nur von NPM.
  • Dashboard-Container hat keinen Schreibzugriff auf state/ (Negativtest) und kein /dev/kfd, /dev/dri.

Folgeänderung für GNMON-000 (Dokumentationsindex)

Beim Einchecken dieser Revision GNMON-000 anpassen:

  • Bestätigter Stand: „Komponenten: node_exporter + AMD-Textfile-Skript, VictoriaMetrics, Loki + Alloy (host-seitig), Dashboard unter gn-dashboard (984) als Blazor-Server-Quadlet; Metriken mit Verlaufshistorie, Logs aus journald, Containern und Encoding."
  • Statuszeile: „Revision v2.0 (03.11.2026): Blazor statt Flask, Zeitreihen- und Log-Stack ergänzt."
  • Noch offen: Punkte 1–6 aus Abschnitt 9 übernehmen; Punkt „system.json-Collector" entfällt.