Update Watcher-Agent
@@ -1,229 +1,99 @@
|
||||
# 🧭 Schnittstellen – Docker Service Broadcasting Agent
|
||||
# Schnittstellen
|
||||
|
||||
## Übersicht
|
||||
## Server Registrierung
|
||||
|
||||
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:
|
||||
Endpoint: /monitoring/register
|
||||
|
||||
1. **Registrierung & Hardware-Erkennung**
|
||||
2. **Service Discovery (Containerliste)**
|
||||
3. **Metrik-Übertragung (alle 30s)**
|
||||
4. **ServerListener (Befehlsabruf und Ausführung)**
|
||||
Beim Start des Agent, überprüft dieser, ob er bereits eine ID vom Watcher-Server zugewiesen bekommen hat.
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ Server Registrierung
|
||||
## Hardware Info
|
||||
|
||||
**Endpoint:**
|
||||
`POST /monitoring/register`
|
||||
Endpoint: /monitoring/hardware-info
|
||||
|
||||
**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.
|
||||
Ist der Agent erfolgreich registriert, schickt er einmalig beim starten seine Hardwareinformationen an den Server.
|
||||
|
||||
**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 |
|
||||
| eingehender Wert | | Einheit |
|
||||
| --- | --- | --- |
|
||||
| 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 |
|
||||
|
||||
**Beispiel Request:**
|
||||
```json
|
||||
{
|
||||
"server_id": "srv-4fd923a1",
|
||||
"cpu_type": "AMD Ryzen 7 5800X",
|
||||
"cpu_cores": 8,
|
||||
"gpu_type": "NVIDIA RTX 3070",
|
||||
"ram_size": 32
|
||||
}
|
||||
```
|
||||
| CpuType| Typ-Bezeichnung des eingebauten CPU | |
|
||||
| CpuCores | Anzahl an CPU-Kernen | |
|
||||
| GpuType| Typ-Bezeichnung der eingebauten Grafikkarte | |
|
||||
| RamSize | Größe des verfügbaren Arbeitsspeichers | |
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ Server Metrics
|
||||
## Server Metrics
|
||||
|
||||
**Endpoint:**
|
||||
`POST /monitoring/metric`
|
||||
Endpoint: /monitoring/metric
|
||||
|
||||
**Beschreibung:**
|
||||
Im 30-Sekunden-Rhythmus sendet der Agent aktuelle Systemmetriken an den Server.
|
||||
Im Serverweiten Tick-Rythmus von 30 Sekunden schickt der Agent einen Metric-Payload an den Server. Dieser Payload beinhaltet die folgenden Werte:
|
||||
|
||||
| Metric | eingehender Wert | umgerechneter Wert |
|
||||
| --- | --- | --- |
|
||||
| CPU_LOAD | % | – |
|
||||
| CPU_TEMP | °C | – |
|
||||
| RAM_LOAD | % | – |
|
||||
| RAM_SIZE | Byte | Gigabyte |
|
||||
| GPU_LOAD | % | – |
|
||||
| GPU_TEMP | °C | – |
|
||||
| GPU_VRAM_LOAD | % | – |
|
||||
| GPU_VRAM_SIZE | Bytes | Gigabyte |
|
||||
| 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 |
|
||||
| NET_RX | Bytes/s | Megabit/s |
|
||||
| NET_TX | Bytes/s | Megabit/s |
|
||||
| DISK_USAGE | Bytes | Gigabyte |
|
||||
| DISK_SIZE | Bytes | Gigabyte |
|
||||
| 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
|
||||
}
|
||||
}
|
||||
```
|
||||
| DISK_TEMP | °C | keine Umrechnung |
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ Service Discovery
|
||||
## Service Discovery
|
||||
|
||||
**Endpoint:**
|
||||
`POST /monitoring/service-discovery`
|
||||
Endpoint: /monitoring/service-discovery
|
||||
|
||||
**Beschreibung:**
|
||||
Beim Start übermittelt der Agent eine Liste aller auf dem Host laufenden Docker-Container.
|
||||
Beim Start schickt der Agent eine Liste aller auf seinem Host laufenden Container:
|
||||
|
||||
| Attribut | Beschreibung | Docker Variable |
|
||||
| --- | --- | --- |
|
||||
| ServerId | ID des Hosts auf dem der Container läuft | – |
|
||||
| ContainerId | Container-ID | `.Id` |
|
||||
| Image | Verwendetes Image | `.Image` |
|
||||
| Name | Name des Containers | `.Names[0]` |
|
||||
| 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 |
|
||||
|
||||
**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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Diese Daten werden einmalig beim Start gesendet und können optional durch einen manuellen Refresh aktualisiert werden.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 5️⃣ Service Metrics *(noch nicht implementiert)*
|
||||
## Service Metrics
|
||||
|
||||
**Geplant:**
|
||||
Erweiterung um container-spezifische Metriken (CPU, RAM, I/O, Netz, Uptime) pro Docker-Container.
|
||||
noch nicht implementiert
|
||||
|
||||
---
|
||||
|
||||
## 6️⃣ ServerListener
|
||||
## 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.
|
||||
Frägt beim Server an ob eine neue (aktive) Message für den Client existiert.
|
||||
Wenn eine existiert, dann kann der Client diese Anfragen und in nutzbare Daten umwandeln.
|
||||
(Im Zuge der Überreichung muss die Nachricht deaktiviert werden - am besten mit einem boolean; wenn die Nachricht stets verfügbar bleibt wird sie immer wieder vom Client abgefragt)
|
||||
|
||||
### **Server Endpoint**
|
||||
`GET /monitoring/messages/{serverId}`
|
||||
Die ServerListenerDto sieht wie folgt aus:
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"message_type": "restart_container",
|
||||
"data": { "container_id": "b3f9d12a9f01" },
|
||||
"message_id": "msg-82d9b3f"
|
||||
}
|
||||
```
|
||||
|
||||
### **Message Structure**
|
||||
```rust
|
||||
/// Command message received from the backend server.
|
||||
///
|
||||
/// ## Fields
|
||||
/// - `message_type`: Type of command (e.g., "update_image", "restart_container", "stop_agent")
|
||||
/// - `data`: Command payload (arbitrary JSON)
|
||||
/// - `message_id`: Unique identifier for acknowledgment
|
||||
#[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 | `{}` |
|
||||
## Message Acknowledgment
|
||||
|
||||
Reference in New Issue
Block a user