nordisk/Skidbladnir

matrix — design

Class: design · Function axis: f9 (machine lifecycle + the live install matrix). Server-side, behind the machine/kvm/matrix features. States only the shape we ship; the why is in matrix-reasoning.md.

Machine lifecycle (machine.rs, feature machine)

pub trait MachineController (machine.rs:273) — one trait, two impls: start, stop (idempotent), exec, wait_ready (machine.rs:275–:281). MachineSpec (machine.rs:124) describes a machine controller-agnostically: image (ImageRef, machine.rs:112), cpus, memory_mb, net (NetMode, machine.rs:53 — Nat | Isolated | Named), provision (Provision, machine.rs:80 — None | CloudInit | Ignition), mounts, readiness (Readiness, machine.rs:94), and the report/agent channels serial_out/qga_sock (machine.rs:145,:150). needs_real_machine() (machine.rs:232) picks KVM over container when isolation, cloud-init, or a systemd-unit readiness is required.

KvmController (machine.rs:481, feature kvm) launches qemu: full_argv (machine.rs:571) builds the q35 argv with per-drive snapshot=on (base image never mutated), -nic none under Isolated, and the two virtio-serial ports org.skidbladnir.report + org.qemu.guest_agent.0. Seed/payload media are authored as pure-Rust FAT images via build_fat_image (machine.rs:511, fatfs) — no genisoimage. exec runs over the qemu-guest-agent (machine.rs:816); ContainerController (machine.rs:891, feature container) is the fast, stateless twin.

ImageCache (machine.rs:312) is content-addressed (SHA-256 keyed blobs + name pointers): put_bytes/put_file (machine.rs:339,:351) dedup by hash, path_for (machine.rs:380) re-hashes on read (verify-on-receipt; corruption is an error), import_znippy_set (machine.rs:439, feature znippy) imports a znippy archive of images.

The install matrix (matrix.rs, feature matrix)

Asserts, as data, that a product installs + starts + stays healthy across OSes (⇒ init backends) inside KVMs. A cell is (OsImage × Backend × scope).

• OsImage (matrix.rs:88) — a cloud base image + its Backend. test_service_spec(scope) (matrix.rs:150) is the trivial skidtest service (TEST_SERVICE, matrix.rs:42) every cell installs, binding TEST_PORT 7070.
• run_cell(...) (matrix.rs:247) runs one cell end-to-end: renderer_for(backend) filter → if None, Skipped{reason:"no renderer"} (honest); else build the payload FAT image (skidbladnir-probe + skidbladnir-testsvc + rendered units), boot the KVM guest, and poll the serial report. render_user_data (matrix.rs:171) is the pure cloud-init that mounts the payload, runs the renderer's enable/start verbs, runs the probe, and tees the ProbeReport to /dev/virtio-ports/org.skidbladnir.report.
• run_matrix(...) (matrix.rs:347) is the cartesian (OS × backend) sweep; sink_results (matrix.rs:368) writes one ProbeReport JSON line per cell to <root>/probe_reports.jsonl and one AirgapEvent (op = matrix_probe) per cell (→ airgap_events, for nornir's autonom ingest).

CellOutcome (matrix.rs:111) = Passed | Unhealthy | NoReport{reason} | Skipped{reason}; ProbeReport (matrix.rs:63) — service, backend, os, running, pid, ports, health, logs_tail, asserted_at; is_healthy() (matrix.rs:81) = running && health.ok.

The injected probe (probe/)

skidbladnir-probe (static musl, std-only) introspects the just-installed service and prints one JSON line: running?/pid (systemd is-active/MainPID, OpenRC rc-service status/pidfile, or a /proc scan fallback), ports (TcpStream::connect), health (ComponentSpec Tcp/Http), logs tail. skidbladnir-testsvc is the trivial "product" it asserts on — binds a port and answers GET /health with 200 OK. Both run under systemd and OpenRC.

Contract

tests/install_matrix_live.rs::live_install_matrix (install_matrix_live.rs:31, #[ignore], heavy) boots 4 OS guests (ubuntu-24.04 / debian-12 / fedora-42 → systemd; alpine-3.21 → OpenRC), runs run_matrix, sinks the rows, and asserts at least two distinct OS guests round-tripped a ProbeReport (install_matrix_live.rs:102).