From c11e1b9c67cd20adc4e08ad3b5cc8257a337b84e Mon Sep 17 00:00:00 2001 From: Patrick Mahnke-Hartmann Date: Thu, 9 Oct 2025 22:39:02 +0200 Subject: [PATCH] Update Watcher-Agent --- Watcher-Agent.-.md | 238 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 202 insertions(+), 36 deletions(-) diff --git a/Watcher-Agent.-.md b/Watcher-Agent.-.md index 65efa8f..7229b28 100644 --- a/Watcher-Agent.-.md +++ b/Watcher-Agent.-.md @@ -1,63 +1,229 @@ -#Schnittstellen +# 🧭 Schnittstellen – Docker Service Broadcasting Agent -## Server Registrierung +## Übersicht -Endpoint: /monitoring/register +Der Agent ist ein autonomer Client, der auf einem Host läuft, Docker-Container verwaltet, Metriken sammelt und mit einem zentralen Watcher-Server kommuniziert. +Der Agent arbeitet zyklisch und nutzt dabei mehrere Subsysteme: -Beim Start des Agent, überprüft dieser, ob er bereits eine ID vom Watcher-Server zugewiesen bekommen hat. +1. **Registrierung & Hardware-Erkennung** +2. **Service Discovery (Containerliste)** +3. **Metrik-Übertragung (alle 30s)** +4. **ServerListener (Befehlsabruf und Ausführung)** -## Hardware Info +--- -Endpoint: /monitoring/hardware-info +## 1️⃣ Server Registrierung -Ist der Agent erfolgreich registriert, schickt er einmalig beim starten seine Hardwareinformationen an den Server. -Übergebene Werte: +**Endpoint:** +`POST /monitoring/register` -| eingehender Wert | | Einheit | +**Beschreibung:** +Beim Start überprüft der Agent, ob ihm bereits eine eindeutige ID vom Watcher-Server zugewiesen wurde. +Fehlt diese, registriert sich der Agent neu. + +**Beispiel Request:** +```json +{ + "hostname": "docker-node-01", + "ip": "192.168.1.10", + "version": "1.0.3" +} +``` + +**Response:** +```json +{ + "server_id": "srv-4fd923a1", + "registered_at": "2025-10-09T10:15:00Z" +} +``` + +--- + +## 2️⃣ Hardware Info + +**Endpoint:** +`POST /monitoring/hardware-info` + +**Beschreibung:** +Nach erfolgreicher Registrierung übermittelt der Agent einmalig beim Start seine Hardwareinformationen an den Server. + +| Attribut | Beschreibung | Einheit | | --- | --- | --- | -| CpuType| Typ-Bezeichnung des eingebauten CPU | -| CpuCores | Anzahl an CPU-Kernen | -| GpuType| Typ-Bezeichnung der eingebauten Grafikkarte | -| RamSize | Größe des verfügbaren Arbeitsspeichers | +| CpuType | Typ-Bezeichnung der eingebauten CPU | Text | +| CpuCores | Anzahl an CPU-Kernen | Anzahl | +| GpuType | Typ-Bezeichnung der Grafikkarte | Text | +| RamSize | Größe des verfügbaren Arbeitsspeichers | GB | -## Server Metrics +**Beispiel Request:** +```json +{ + "server_id": "srv-4fd923a1", + "cpu_type": "AMD Ryzen 7 5800X", + "cpu_cores": 8, + "gpu_type": "NVIDIA RTX 3070", + "ram_size": 32 +} +``` -Endpoint: /monitoring/metric +--- -Im Serverweiten Tick-Rythmus von 30 Sekunden schickt der Agent einen Metric-Payload an den Server. Dieser Payload beinhaltet die folgenden Werte: +## 3️⃣ Server Metrics + +**Endpoint:** +`POST /monitoring/metric` + +**Beschreibung:** +Im 30-Sekunden-Rhythmus sendet der Agent aktuelle Systemmetriken an den Server. | Metric | eingehender Wert | umgerechneter Wert | | --- | --- | --- | -| CPU_LOAD | prozentual | keine Umrechnung| -| CPU_TEMP | °C | keine Umrechnung | -| RAM_LOAD | prozentual | keine Umrechnung | -| RAM_SIZE | Byte | GigaByte | -| GPU_LOAD | prozentual | keine Umrechnung | -| GPU_TEMP | °C | keine Umrechnung| -| GPU_VRAM_LOAD | prozentual | keine Umrechnung | -| GPU_VRAM_SIZE | Bytes | GigaByte | +| CPU_LOAD | % | – | +| CPU_TEMP | °C | – | +| RAM_LOAD | % | – | +| RAM_SIZE | Byte | Gigabyte | +| GPU_LOAD | % | – | +| GPU_TEMP | °C | – | +| GPU_VRAM_LOAD | % | – | +| GPU_VRAM_SIZE | Bytes | Gigabyte | | NET_RX | Bytes/s | Megabit/s | | NET_TX | Bytes/s | Megabit/s | | DISK_USAGE | Bytes | Gigabyte | | DISK_SIZE | Bytes | Gigabyte | -| DISK_TEMP | °C | keine Umrechnung | +| DISK_TEMP | °C | – | +**Beispiel Request:** +```json +{ + "server_id": "srv-4fd923a1", + "metrics": { + "CPU_LOAD": 12.4, + "CPU_TEMP": 53.0, + "RAM_LOAD": 64.8, + "RAM_SIZE": 32, + "GPU_LOAD": 27.3, + "GPU_TEMP": 48.0, + "GPU_VRAM_LOAD": 21.1, + "GPU_VRAM_SIZE": 8, + "NET_RX": 3.2, + "NET_TX": 1.1, + "DISK_USAGE": 125.6, + "DISK_SIZE": 500, + "DISK_TEMP": 39.0 + } +} +``` -## Service Discovery +--- -Endpoint: /monitoring/service-discovery +## 4️⃣ Service Discovery -Beim Start schickt der Agent eine Liste aller auf seinem Host laufenden Container: +**Endpoint:** +`POST /monitoring/service-discovery` + +**Beschreibung:** +Beim Start übermittelt der Agent eine Liste aller auf dem Host laufenden Docker-Container. | Attribut | Beschreibung | Docker Variable | | --- | --- | --- | -| ServerId | ID des Hosts auf dem der Container läuft | # | -| ContainerId | ID des Containers auf dem Host | ? | -| Image | Image, das der Container verwendet | image | -| Name | Name den der Container auf dem Host hat| container_name | +| ServerId | ID des Hosts auf dem der Container läuft | – | +| ContainerId | Container-ID | `.Id` | +| Image | Verwendetes Image | `.Image` | +| Name | Name des Containers | `.Names[0]` | -Diese Daten werden einmalig gesendet und können über einen manuellen refresh aktualisert werden (kommt irgendwann). -ContainerId / Image / Name werden in Form eines Container Objektes in json-Format übergeben. +**Beispiel Request:** +```json +{ + "server_id": "srv-4fd923a1", + "containers": [ + { + "container_id": "b3f9d12a9f01", + "image": "nginx:latest", + "name": "web_service" + }, + { + "container_id": "6e2b11a8c909", + "image": "mysql:8.0", + "name": "db_service" + } + ] +} +``` -## Service Metrics -noch nicht implementiert +Diese Daten werden einmalig beim Start gesendet und können optional durch einen manuellen Refresh aktualisiert werden. + +--- + +## 5️⃣ Service Metrics *(noch nicht implementiert)* + +**Geplant:** +Erweiterung um container-spezifische Metriken (CPU, RAM, I/O, Netz, Uptime) pro Docker-Container. + +--- + +## 6️⃣ ServerListener + +**Funktion:** +Der Agent fragt periodisch beim Server nach, ob neue Befehle für ihn vorliegen. +Falls eine Nachricht vorhanden ist, wird sie abgerufen, verarbeitet und anschließend deaktiviert. + +### **Server Endpoint** +`GET /monitoring/messages/{serverId}` + +**Response:** +```json +{ + "message_type": "restart_container", + "data": { "container_id": "b3f9d12a9f01" }, + "message_id": "msg-82d9b3f" +} +``` + +### **Message Structure** +```rust +#[derive(Debug, Deserialize, Clone)] +pub struct ServerMessage { + /// Type of command (e.g., "update_image", "restart_container", "stop_agent") + pub message_type: String, + + /// Command payload (arbitrary JSON) + pub data: serde_json::Value, + + /// Unique identifier for acknowledgment + pub message_id: String, +} +``` + +--- + +## 7️⃣ Message Acknowledgment + +**Endpoint:** +`POST /monitoring/messages/{messageId}/ack` + +**Beschreibung:** +Nach erfolgreicher Ausführung der Nachricht deaktiviert der Agent die Nachricht auf dem Server. +Dies verhindert, dass der gleiche Befehl mehrfach ausgeführt wird. + +**Beispiel Request:** +```json +{ + "server_id": "srv-4fd923a1", + "acknowledged_at": "2025-10-09T10:22:14Z" +} +``` + +**Server-Action:** +- Setze `is_active = false` für die Nachricht +- Protokolliere den Zeitpunkt der Acknowledgment + +--- + +## 8️⃣ Message Types (Beispiele) + +| Message Type | Beschreibung | Beispiel Payload | +| --- | --- | --- | +| `restart_container` | Startet einen angegebenen Container neu | `{ "container_id": "b3f9d12a9f01" }` | +| `update_image` | Aktualisiert ein Docker-Image | `{ "image": "nginx:latest" }` | +| `stop_agent` | Stoppt den Agent-Prozess | `{}` | +| `refresh_services` | Erzwingt ein erneutes Senden der Containerliste | `{}` |