commit 26c0cced392981e8f34a853181eb47c57d3c3f7d Author: Brad Stein Date: Sat Jan 10 20:52:37 2026 -0300 init: scaffold metis design diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ee0a58 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# Metis + +Metis produces fully configured recovery SD cards for any node in the lab (RPi 4/5 workers, control plane Pis, amd64 nodes like tethys, titan-db, titan-jh, future titan-20/21, and non-cluster hosts). Goal: 1 command + insert SD → node rejoins with identical identity, network, k3s role/labels/taints, and pre-baked log/GC drop-ins. + +## Objectives +- Cross-platform (Linux + Windows) CLI/GUI with dead-simple UX. +- Pull class-specific golden images from Harbor (or other artifact store), inject per-node config, and write/verify SD cards. +- Minimal image set via node classes; inject per-node deltas at burn time. +- Idempotent bootstraps: hostname/IP, k3s server/agent setup, labels/taints, journald/log GC drop-ins, Longhorn mount validation, SSH keys/users. +- Works offline once artifacts are cached; verifies hashes/signatures before writing. + +## Planned high-level workflow +1) Select target node (from inventory) + target disk. +2) Tool downloads/caches the right golden image for that node class. +3) Injects per-node config (net, k3s tokens/roles/labels/taints, SSH keys, runtime drop-ins, Longhorn mount metadata) and writes SD. +4) Verifies write; prints next-step: "insert and power on." No manual follow-up. + +## Early design notes +- Implemented in Go for easy static builds and a lightweight GUI (e.g., Fyne or Wails) plus CLI. +- Inventory-driven: node classes (rpi5-ubuntu, rpi4-armbian-longhorn, rpi4-armbian-std, control-plane, amd64-agents, external hosts). +- Extensible per-node hooks for special hardware (Longhorn HDD UUIDs on titan-13/15/17/19; future titan-20/21; oceanus/titan-23; tethys/titan-jh/titan-db). +- Secure defaults: hash checking for downloaded images; avoids ever printing secrets; prepares k3s tokens/certs/keys via sealed source. + +## Repo layout (initial) +- `cmd/` – CLI/GUI entrypoints +- `pkg/` – shared lib (inventory, imaging, injectors, platform abstraction) +- `docs/` – user/operator docs (this will stay light; working notes live in AGENTS.md untracked) +- `AGENTS.md` – local, untracked working notes (do not add to git) diff --git a/docs/node-classes.md b/docs/node-classes.md new file mode 100644 index 0000000..9b79cef --- /dev/null +++ b/docs/node-classes.md @@ -0,0 +1,12 @@ +# Node classes (draft) + +Initial classes to minimize golden images while covering hardware/OS deltas: + +- `rpi5-ubuntu-worker`: Ubuntu 24.04, k3s agent, hardware=rpi5 (titan-04..11, 0a/0c minus control-plane bits) +- `rpi5-ubuntu-control`: Ubuntu 24.04, k3s server (titan-0a/0b/0c specifics), control-plane taints, etcd snapshot hooks +- `rpi4-armbian-longhorn`: Armbian 6.6.x, k3s agent, hardware=rpi4 with Longhorn disks (titan-13/15/17/19; astreae/asteria mounts) +- `rpi4-armbian-worker`: Armbian 6.6.x, k3s agent, hardware=rpi4 without Longhorn disks (titan-12/14/18) +- `amd64-agent`: Debian 13 k3s agent with GPU/node labels (titan-22/24, avoid by preference) +- `external-hosts`: non-cluster (tethys, titan-db, titan-jh, oceanus/titan-23, future titan-20/21) – per-host config over base image template + +Per-node overlays capture hostname/IP, labels/taints, Longhorn UUID mounts, and drop-ins for logging/GC.