[Vision/Konzept] Generic-Host-Agent: Nicht-Proxmox-Hosts (NAS/Standalone) ins System aufnehmen #190

New issue

Open

opened 2026-06-26 14:55:03 +00:00 by chinux · 0 comments

chinux commented

2026-06-26 14:55:03 +00:00

Owner

Status: KONZEPT / Planung (Vision-Epic) — später bauen

Ziel: Hosts ins System aufnehmen, die NICHT über einen Proxmox-Host laufen (NAS, Raspi, Standalone-Linux-Server, Switch mit Linux …). Eigener schlanker Generic-Host-Agent mit vollem Funktionsumfang (Monitoring + Updates + Reboot + Command-Ausführung + Docker-Management).

Warum das ein Architektur-Schritt ist (nicht nur ein Feature)

Heute gibt es zwei Agent-Typen, beide an Proxmox gebunden:

Node-Agent: läuft auf dem PVE-Host (pvesh/qm/pct), verbindet direkt zum Backend.
VM/CT-Agent: läuft im PVE-Gast, relayed über den Node-Agent (:9100).
Ein NAS passt in keinen: kein PVE-Host "darüber" zum Relayen, selbst kein Hypervisor. → dritter Agent-Typ nötig.

Designentscheidung (getroffen)

Eigener schlanker theprox-host-agent (separat vom Node-Agent), NICHT Node-Agent-Umbau, NICHT Relay.

Verbindung — wiederverwendet die schon gehärtete Strecke

Verbindet direkt zum Backend wie der Node-Agent (kein Relay). Nutzt dieselbe Maschinerie:

#185 ed25519 Challenge-Response-Auth (eigene Identity pro Host).
#187/#189 Transport: wss/https Default, VPN-Toggle/Klartext-Opt-in, Self-Update via TLS+sha256.
#117 Command-Allowlist-Muster.
Das ist die einfache Hälfte — die Strecke existiert bereits.

Funktionsumfang (voll)

Host-Metrics: CPU/RAM/Disk/SMART/Load/Uptime/Dienste.
Updates: apt/dnf (OS-Erkennung), Reboot-needed-Meldung (kein Auto-Reboot, analog Node).
Reboot, Command-Ausführung (Allowlist, root).
Docker-Management: Container/Compose — die Logik existiert bereits im VM-Guest-Agent (collect/mod.rs docker/compose_check/update) → wiederverwenden, nicht neu schreiben. (Profitiert vom Multi-Arch-Digest-Fix #91.)

KERN-AUFWAND: Backend-Modell + UI müssen "Host ohne Gäste" können

Auch mit separatem Agent bleibt Backend/UI-Arbeit unvermeidbar:

Node.kind (neu): proxmox | generic_host (Default proxmox; Migration). Es gibt KEIN Typ-Feld heute.
Ein generic_host hat keine VMs/CTs — Telemetrie-Ingest, Scheduler-Kandidaten (#174), Bulk-Update (#123) müssen das sauber behandeln (kein VM-Scan, keine VM-Liste).
UI: Host-Karte ohne VM-Liste, mit Metrics + Updates + Command + Docker. NodeCard (#94) muss je kind unterschiedlich rendern.
Mandanten-Scope (#108-Muster) gilt unverändert.

Wichtig: gemeinsames Rust-Crate ZUERST (sonst Code-Duplikation)

Es gibt keinen Cargo-Workspace; Node-/VM-/Win-Agent duplizieren bereits Logik (WS-Client, run_cmd, collect/docker, künftig auth/identity #185, transport #187, self-update). Ein vierter Agent würde das verschärfen.
→ Voraussetzung/Begleit-Arbeit: gemeinsame Bausteine in ein shared crate (Cargo-Workspace) ziehen — WS/Reconnect, ed25519-Identity+Handshake, Transport-Validierung, Self-Update, run_cmd, Docker-Collect. Host-Agent UND Node-Agent nutzen es. (Das war schon im Struktur-Review als Schwäche notiert.)

Offene Punkte (vor dem Bau zu klären)

Enrollment-Flow für Nicht-PVE-Hosts (Install-Script-Variante; #189-Transport-Toggle gilt auch hier).
Abgrenzung zu #68 (Hypervisor-Abstraktion): generic_host = "Hypervisor mit 0 Gästen" oder eigene Klasse? Capability-Konzept (host_metrics/docker/updates) als gemeinsame Basis?
Windows-Generic-Host? (vorerst Linux-only annehmen, Windows später).
Naming/Binary: theprox-host-agent, systemd-Unit, Pfade.

Bezug

#68 (Hypervisor-Abstraktion — verwandt), Struktur-Review (Rust-Workspace/shared crate), #185/#187/#189 (Auth/Transport — wiederverwendet), #117 (Allowlist), #91 (Docker-Digest), #94 (NodeCard-Rendering), #123/#174 (VM-Annahmen entkoppeln).

NICHT JETZT

Reines Konzept. Bau erst nach Priorisierung; Voraussetzung ist das shared crate.

## Status: KONZEPT / Planung (Vision-Epic) — später bauen Ziel: Hosts ins System aufnehmen, die **NICHT über einen Proxmox-Host laufen** (NAS, Raspi, Standalone-Linux-Server, Switch mit Linux …). Eigener schlanker **Generic-Host-Agent** mit vollem Funktionsumfang (Monitoring + Updates + Reboot + Command-Ausführung + Docker-Management). ## Warum das ein Architektur-Schritt ist (nicht nur ein Feature) Heute gibt es zwei Agent-Typen, **beide an Proxmox gebunden**: - **Node-Agent**: läuft *auf* dem PVE-Host (pvesh/qm/pct), verbindet direkt zum Backend. - **VM/CT-Agent**: läuft *im* PVE-Gast, relayed über den Node-Agent (:9100). Ein NAS passt in keinen: kein PVE-Host "darüber" zum Relayen, selbst kein Hypervisor. → dritter Agent-Typ nötig. ## Designentscheidung (getroffen) **Eigener schlanker `theprox-host-agent`** (separat vom Node-Agent), NICHT Node-Agent-Umbau, NICHT Relay. ### Verbindung — wiederverwendet die schon gehärtete Strecke Verbindet **direkt zum Backend** wie der Node-Agent (kein Relay). Nutzt dieselbe Maschinerie: - **#185** ed25519 Challenge-Response-Auth (eigene Identity pro Host). - **#187/#189** Transport: wss/https Default, VPN-Toggle/Klartext-Opt-in, Self-Update via TLS+sha256. - **#117** Command-Allowlist-Muster. Das ist die *einfache* Hälfte — die Strecke existiert bereits. ### Funktionsumfang (voll) - Host-Metrics: CPU/RAM/Disk/SMART/Load/Uptime/Dienste. - Updates: apt/dnf (OS-Erkennung), Reboot-needed-Meldung (kein Auto-Reboot, analog Node). - Reboot, Command-Ausführung (Allowlist, root). - **Docker-Management**: Container/Compose — die Logik existiert bereits im VM-Guest-Agent (`collect/mod.rs` docker/compose_check/update) → wiederverwenden, nicht neu schreiben. (Profitiert vom Multi-Arch-Digest-Fix #91.) ## KERN-AUFWAND: Backend-Modell + UI müssen "Host ohne Gäste" können Auch mit separatem Agent bleibt Backend/UI-Arbeit unvermeidbar: - **`Node.kind`** (neu): `proxmox` | `generic_host` (Default proxmox; Migration). Es gibt KEIN Typ-Feld heute. - Ein `generic_host` hat **keine VMs/CTs** — Telemetrie-Ingest, Scheduler-Kandidaten (#174), Bulk-Update (#123) müssen das sauber behandeln (kein VM-Scan, keine VM-Liste). - **UI**: Host-Karte ohne VM-Liste, mit Metrics + Updates + Command + Docker. NodeCard (#94) muss je `kind` unterschiedlich rendern. - Mandanten-Scope (#108-Muster) gilt unverändert. ## Wichtig: gemeinsames Rust-Crate ZUERST (sonst Code-Duplikation) Es gibt **keinen Cargo-Workspace**; Node-/VM-/Win-Agent duplizieren bereits Logik (WS-Client, run_cmd, collect/docker, künftig auth/identity #185, transport #187, self-update). Ein vierter Agent würde das verschärfen. → **Voraussetzung/Begleit-Arbeit**: gemeinsame Bausteine in ein **shared crate** (Cargo-Workspace) ziehen — WS/Reconnect, ed25519-Identity+Handshake, Transport-Validierung, Self-Update, run_cmd, Docker-Collect. Host-Agent UND Node-Agent nutzen es. (Das war schon im Struktur-Review als Schwäche notiert.) ## Offene Punkte (vor dem Bau zu klären) - [ ] Enrollment-Flow für Nicht-PVE-Hosts (Install-Script-Variante; #189-Transport-Toggle gilt auch hier). - [ ] Abgrenzung zu #68 (Hypervisor-Abstraktion): generic_host = "Hypervisor mit 0 Gästen" oder eigene Klasse? Capability-Konzept (`host_metrics`/`docker`/`updates`) als gemeinsame Basis? - [ ] Windows-Generic-Host? (vorerst Linux-only annehmen, Windows später). - [ ] Naming/Binary: `theprox-host-agent`, systemd-Unit, Pfade. ## Bezug #68 (Hypervisor-Abstraktion — verwandt), Struktur-Review (Rust-Workspace/shared crate), #185/#187/#189 (Auth/Transport — wiederverwendet), #117 (Allowlist), #91 (Docker-Digest), #94 (NodeCard-Rendering), #123/#174 (VM-Annahmen entkoppeln). ## NICHT JETZT Reines Konzept. Bau erst nach Priorisierung; Voraussetzung ist das shared crate.

chinux added the

tech-debt

agent

labels

2026-06-26 14:55:03 +00:00