Document full architecture, design, API, features, deployment, and security.
Adds diagrams and expands the ATC demo path so the cockpit is fully described in-repo.
This commit is contained in:
mo
+203
@@ -0,0 +1,203 @@
|
||||
# API reference
|
||||
|
||||
Base URL (lab): `http://atc-portal01.dell-atc.lan:3090`
|
||||
Internal container port: `8090`
|
||||
|
||||
All JSON unless noted. No auth middleware in lab build (protect at network edge).
|
||||
|
||||
---
|
||||
|
||||
## Health & fleet
|
||||
|
||||
### `GET /api/health`
|
||||
|
||||
```json
|
||||
{ "status": "ok", "updated_at": 1784252683.4, "pulse": 12 }
|
||||
```
|
||||
|
||||
### `GET /api/fleet`
|
||||
|
||||
Full in-memory snapshot:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `ome` | Appliance name/version/url |
|
||||
| `summary` | totals, connected, offline, watts, samples |
|
||||
| `devices[]` | normalized nodes |
|
||||
| `subnets[]` | /24 aggregates |
|
||||
| `groups[]` | OME groups (names) |
|
||||
| `models[]` | server model counts |
|
||||
| `alerts[]` | recent alert feed |
|
||||
| `events[]` | fleet deltas (incl. device_new/removed) |
|
||||
| `context` | alert_severity, hottest, notifications, … |
|
||||
| `gpu` | latest GPU matrix |
|
||||
| `pulse` | monotonic refresh counter |
|
||||
| `openwebui_url` | companion AI URL |
|
||||
|
||||
### `WS /ws/fleet`
|
||||
|
||||
- On connect: immediate `{type:"snapshot", data}`
|
||||
- Then server pushes `{type:"snapshot"}` / `{type:"gpu"}` / `{type:"error"}`
|
||||
- Client may send any text ping; server mainly broadcasts
|
||||
|
||||
---
|
||||
|
||||
## Devices
|
||||
|
||||
### `GET /api/devices/{device_id}`
|
||||
|
||||
On-demand OME inventory enrichment.
|
||||
|
||||
Response highlights:
|
||||
|
||||
```json
|
||||
{
|
||||
"device": { "...fleet node..." },
|
||||
"power": { "watts": 320, "avg_watts": 300, "peak_watts": 400, "energy_kwh": 12.3 },
|
||||
"inventory_types": ["serverProcessors", "deviceSoftware", "..."],
|
||||
"inventory": { "deviceSoftware": [ /* raw OME rows */ ], "...": [] },
|
||||
"landscape": {
|
||||
"os": [],
|
||||
"software": [],
|
||||
"firmware": [],
|
||||
"drivers": [],
|
||||
"applications": [],
|
||||
"management": [],
|
||||
"licenses": []
|
||||
},
|
||||
"_ts": 1784252700.0
|
||||
}
|
||||
```
|
||||
|
||||
Cached ~300 seconds per device.
|
||||
|
||||
---
|
||||
|
||||
## GPU
|
||||
|
||||
### `GET /api/gpu`
|
||||
|
||||
Latest GPU sidecar payload (also present on fleet snapshot).
|
||||
|
||||
---
|
||||
|
||||
## Chat & models
|
||||
|
||||
### `GET /api/models`
|
||||
|
||||
```json
|
||||
{
|
||||
"default": "llama3-70b-gptq",
|
||||
"models": [
|
||||
{ "id": "llama3-70b-gptq", "name": "llama3-70b-gptq", "source": "openwebui|vllm" },
|
||||
{ "id": "ome-copilot", "name": "OME Copilot", "source": "openwebui" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/chat`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "List critical systems",
|
||||
"history": [{ "role": "user", "content": "..." }],
|
||||
"focus_device_id": 50374,
|
||||
"model": "llama3-70b-gptq"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"reply": "...",
|
||||
"model": "llama3-70b-gptq",
|
||||
"backend": "vllm|openwebui",
|
||||
"gpu": {},
|
||||
"context_bytes": 4104
|
||||
}
|
||||
```
|
||||
|
||||
Errors: `502` with upstream detail (context length, auth, etc.).
|
||||
|
||||
---
|
||||
|
||||
## Tickets (Ops desk)
|
||||
|
||||
Admins (fixed lab list): `jody`, `laurens` (+ names in API).
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET | `/api/admins` | Admin directory |
|
||||
| GET | `/api/tickets` | List tickets |
|
||||
| POST | `/api/tickets` | Create |
|
||||
| GET | `/api/tickets/{id}` | Detail + messages |
|
||||
| POST | `/api/tickets/{id}/messages` | Add note |
|
||||
| PATCH | `/api/tickets/{id}` | status / assignee / priority / accepted_by |
|
||||
| DELETE | `/api/tickets/{id}` | Delete |
|
||||
|
||||
SQLite file: `$COCKPIT_DATA/ops.db` (default `/data/ops.db`).
|
||||
|
||||
---
|
||||
|
||||
## SSH
|
||||
|
||||
### `WS /ws/ssh`
|
||||
|
||||
**Message 1 (client → server):**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "auth",
|
||||
"host": "10.0.41.50",
|
||||
"port": 22,
|
||||
"username": "jody",
|
||||
"password": "***",
|
||||
"cols": 120,
|
||||
"rows": 40,
|
||||
"term": "xterm-256color"
|
||||
}
|
||||
```
|
||||
|
||||
**Server control messages:** `{type:"status|ready|error|pong", message?: string}`
|
||||
**Thereafter:** raw terminal bytes as WebSocket text.
|
||||
|
||||
**Client control (optional JSON):**
|
||||
|
||||
```json
|
||||
{ "type": "resize", "cols": 100, "rows": 30 }
|
||||
{ "type": "ping" }
|
||||
```
|
||||
|
||||
Constraints:
|
||||
|
||||
- `host` must appear as a management IP in the current fleet snapshot
|
||||
- Max 25 concurrent bridges; max 3 per client IP
|
||||
- Idle timeout ~30 minutes
|
||||
|
||||
### `GET /api/ssh/sessions`
|
||||
|
||||
Ops visibility (no secrets):
|
||||
|
||||
```json
|
||||
{ "active": 2, "max": 25, "sessions": [{ "id": "...", "client": "10.0.10.65", "host": "10.0.41.50", "user": "jody", "age_sec": 42 }] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Static assets
|
||||
|
||||
| Path | File |
|
||||
|------|------|
|
||||
| `/` | `ui/index.html` (no-store cache) |
|
||||
| `/app.js` `/ops.js` `/ssh.js` `/styles.css` | UI |
|
||||
| `/vendor/xterm/*` | Terminal library |
|
||||
| `/dell.png` etc. | Branding |
|
||||
|
||||
---
|
||||
|
||||
## Environment (settings)
|
||||
|
||||
Mapped via `pydantic-settings` from `.env` (see `.env.example`):
|
||||
|
||||
`OME_URL`, `OME_USER`, `OME_PASSWORD`, `POLL_INTERVAL`, `OPENWEBUI_URL`, `OPENWEBUI_EMAIL`, `OPENWEBUI_PASSWORD`, `GPU_METRICS_URL`, `VLLM_URL`, `VLLM_MODEL`, `VLLM_MAX_TOKENS`, `CHAT_SYSTEM_CHARS`, `COCKPIT_DATA`, `CORS_ORIGINS`
|
||||
Reference in New Issue
Block a user