Audiobuzz
80cbb833cc
The steady-state host<->manager transport, resolving the design's OPEN FORK to bespoke gRPC (not OTLP+Wazuh). One long-lived, host-dialed, mTLS bidi stream: health/metrics up, desired-state/commands down — no polling, real-time control, still no inbound host port. - proto/fleet_agent.proto: FleetAgent.Session(stream AgentUp) -> stream ManagerDown. AgentUp = Hello | HealthSnapshot | CommandResult; ManagerDown = DesiredState | Command(reboot/drain/resync). int64 unix times (no well-known-type dep). Generated stubs committed (CI needs no protoc). - agent.go: gRPC server with mTLS verified by the FLEET CA (the host's reused TPM identity cert — distinct from the admin plane's admin CA). Identity is the peer cert SERIAL, taken from the verified cert = inventory key, never self-asserted; an unenrolled serial is refused (enrolment gates the stream). Per-conn send channel decouples admin pushes from stream.Send. Stream registry (serial->conn) with reconnect eviction. On connect + on change, desired-state is pushed live; inventory stays authoritative so offline hosts reconcile on reconnect. Metrics go through a MetricsSink seam (no-op now; InfluxDB in ckpt 4). - main.go: agent plane starts only when its cert/key/CA are set; admin can run standalone. Lifecycle PUT now live-pushes and reports pushed_live. Full mTLS integration test (in-process fleet CA + host client cert): initial desired-state on connect, Hello+snapshot -> inventory + online presence, live desired-state push, and unenrolled-serial rejection. go build/test/vet/gofmt clean. Deps (server-side only): google.golang.org/grpc + protobuf.
111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# fleet-manager — server-side fleet control plane
|
|
|
|
The management service for the diskless kiosk fleet, and the backend for the
|
|
admin SPA. It is the central place to **monitor**, **authorise**, and
|
|
**lifecycle-control** enrolled hosts. See
|
|
[`docs/fleet-management-design.md`](../../docs/fleet-management-design.md) and
|
|
[`docs/tpm-enrolment-design.md`](../../docs/tpm-enrolment-design.md) §5.
|
|
|
|
Unlike `fleet-hostapi` / `fleet-enrol` (baked into the reproducible verity image,
|
|
stdlib-only), this runs **server-side** as its own container on the management
|
|
network, so external deps are fine (`grpc-go`, `influxdb-client-go`).
|
|
|
|
## Two mTLS planes (distinct trust anchors)
|
|
|
|
| Plane | Transport | Verifies | Who | Purpose |
|
|
|---|---|---|---|---|
|
|
| **admin** | HTTPS + mTLS | **dedicated admin CA** (`admin-pki.sh`) | admin browsers | JSON API + SPA (monitor / authorise / lifecycle) |
|
|
| **agent** | gRPC + mTLS | **fleet CA** (host TPM cert) | enrolled hosts | bidi stream: health/metrics up, desired-state down |
|
|
|
|
The split is load-bearing: the agent plane uses the host's **reused TPM identity
|
|
cert** (the same one used for 802.1X EAP-TLS and from which the NVMe `hostnqn`
|
|
derives — "one identity, three stages"), while the admin plane uses a **separate**
|
|
CA so an enrolled host can never reach approve/deny/lifecycle. See the identity
|
|
discussion in the enrolment design §5.
|
|
|
|
## Monitoring path (no host ever touches InfluxDB)
|
|
|
|
```
|
|
host agent ──gRPC bidi (mTLS, TPM cert)──▶ fleet-manager ──line protocol──▶ InfluxDB
|
|
◀──── desired-state (target ver / kiosk_url / reboot / drain) ──┘ (+ inventory health)
|
|
SPA ──GET /api/hosts/{serial}/metrics──▶ fleet-manager ──Flux──▶ InfluxDB ──JSON──▶ SPA renders charts
|
|
```
|
|
|
|
Hosts hold **no InfluxDB credential** and never reach it; the manager is the only
|
|
writer/reader, holding the Influx token server-side. Identity is taken from the
|
|
mTLS cert (anti-spoofing: a host can only write its own series). Push-only, no
|
|
inbound host port. Graphs are rendered **in the SPA**, not Grafana.
|
|
|
|
## Inventory record
|
|
|
|
Keyed by TPM **cert serial** (= hostnqn key). Born at enrolment approval, filled
|
|
by the agent stream and admin action:
|
|
|
|
```
|
|
Host (cert_serial)
|
|
├─ identity : cert_serial, hostnqn, mac, ek_hash, starship_name
|
|
├─ binding : asset_tag, switch_port, location (recorded at approval)
|
|
├─ enrolled : approver, at, fingerprint
|
|
├─ version : image_version, rootfs_digest, kernel (agent-reported)
|
|
├─ health : load, cpu, temp, tmpfs%, nvme_root, auth, selinux, chrony, kiosk (latest snapshot; series in InfluxDB)
|
|
├─ usage : kiosk_url, session_uptime, chromium_crashes, display
|
|
└─ desired : target_version, kiosk_url, reboot_at, drain (SERVER-AUTHORITATIVE)
|
|
```
|
|
|
|
Persisted as a single JSON file (atomic writes) on a mounted volume — stdlib-only,
|
|
inspectable, reproducible; a DB swap is a drop-in behind the `Store` interface.
|
|
|
|
## API (admin plane)
|
|
|
|
| Route | Status |
|
|
|---|---|
|
|
| `GET /healthz` | ✅ ckpt 1 |
|
|
| `GET /api/hosts` | ✅ ckpt 1 — fleet overview |
|
|
| `GET /api/hosts/{serial}` | ✅ ckpt 1 — host detail |
|
|
| `PUT /api/hosts/{serial}/desired` | ✅ ckpt 1 — set desired-state (audited to admin CN) |
|
|
| `GET /api/enrol/pending`, `POST /api/enrol/{id}/approve\|deny` | ⏳ ckpt 3 (drives the broker) |
|
|
| `GET /api/hosts/{serial}/metrics` | ⏳ ckpt 4 (InfluxDB/Flux) |
|
|
|
|
**Agent plane** — gRPC `FleetAgent.Session` bidi over mTLS (fleet CA): ✅ ckpt 2.
|
|
`Hello`/`HealthSnapshot`/`CommandResult` up; `DesiredState`/`Command` down.
|
|
Identity is the peer cert serial (never self-asserted); an unenrolled serial is
|
|
refused. Desired-state is pushed live on connect + on change, and is durable in
|
|
inventory for offline delivery. Metrics writing is behind a `MetricsSink`
|
|
(no-op now; InfluxDB in ckpt 4).
|
|
|
|
## Config (env)
|
|
|
|
| Var | Default | Notes |
|
|
|---|---|---|
|
|
| `FLEET_MGR_ADMIN_ADDR` | `127.0.0.1:9500` | admin listener |
|
|
| `FLEET_MGR_ADMIN_CERT` / `_KEY` | — | admin server cert/key (mTLS) |
|
|
| `FLEET_MGR_ADMIN_CLIENT_CA` | — | **dedicated admin CA** (NOT the fleet CA) |
|
|
| `FLEET_MGR_ADMIN_INSECURE` | `false` | plaintext, no client-cert — **dev only** |
|
|
| `FLEET_MGR_AGENT_ADDR` | `127.0.0.1:9600` | gRPC agent listener |
|
|
| `FLEET_MGR_AGENT_CERT` / `_KEY` | — | agent-plane server cert/key |
|
|
| `FLEET_MGR_AGENT_CLIENT_CA` | — | **fleet CA** (verifies host TPM certs). Agent plane starts only when all three are set. |
|
|
| `FLEET_MGR_INVENTORY` | `/var/lib/fleet-manager/inventory.json` | inventory file (mount a volume) |
|
|
| `FLEET_MGR_SEED` | `false` | inject demo hosts so the SPA has data — dev only |
|
|
| `HOSTNQN_BASE` | `nqn.2026-06.org.example.fleet:host-` | hostnqn prefix (match the broker) |
|
|
|
|
InfluxDB env lands in checkpoint 4.
|
|
|
|
## Dev run
|
|
|
|
```bash
|
|
FLEET_MGR_ADMIN_INSECURE=true FLEET_MGR_SEED=true \
|
|
FLEET_MGR_ADMIN_ADDR=127.0.0.1:9500 FLEET_MGR_INVENTORY=/tmp/inv.json \
|
|
go run .
|
|
curl -s localhost:9500/api/hosts | jq '.hosts[] | {name:.identity.starship_name, run:.version.image_version, want:.desired.target_version, online}'
|
|
```
|
|
|
|
## Build status
|
|
|
|
- **Checkpoint 1 (done):** Go skeleton, JSON-file inventory `Store`, admin JSON API
|
|
(monitor + lifecycle), admin mTLS wiring, dev seed. Stdlib-only.
|
|
- **Checkpoint 2 (done):** gRPC agent plane — proto contract, mTLS (fleet CA)
|
|
server, stream registry, identity-from-cert, snapshot→inventory, live
|
|
desired-state push, `MetricsSink` seam. Full mTLS integration test.
|
|
- Next: authorise/broker fold-in (ckpt 3) → InfluxDB read/write (ckpt 4) → themed
|
|
SPA (ckpt 5) → Docker/compose + PKI + docs (ckpt 6).
|