docs(init): validate v0.6 specification

---ci---
project: orca
phase: 0
milestone: v0.6
status: specify
---/ci---
This commit is contained in:
Jon Chery
2026-08-03 19:32:53 +00:00
parent df8d5f5c80
commit fd2c57afeb
5 changed files with 92 additions and 8 deletions
+51
View File
@@ -191,3 +191,54 @@ edit coreci/orca --private=false` so that `install.sh` can pull
release binaries unauthenticated (REQ-045). This is an operational
step performed during the P0 ship, verified by an unauth `curl`
against the releases API.
## v0.6 Scope Summary — Node Bootstrap & Proxmox
v0.6 is a 3-execution-phase milestone that turns `orca init` from a
bare `mkdir` into a full single-node cluster bootstrap, and adds
Proxmox 8 & 9 as a first-class remote node type joined over SSH with
least-privilege role delegation. The engine functionality from
v0.1v0.5 is unchanged; this milestone is about **bootstrap
ergonomics** and **heterogeneous node support**:
- **P01 — `orca init` full bootstrap.** A single `orca init` call now:
(a) creates the namespace dir (`~/.orca` or `/root/.orca` with
`--system`); (b) runs all DB migrations including the new 0006
(`nodes.kind`, `nodes.os` — backward-compatible nullable columns);
(c) bootstraps the internal CA via `security.CAInit` if `ca.crt` is
absent; (d) generates the server cert via `security.GenerateCSR` +
`ca.SignCSR` if `server.crt` is absent; (e) auto-detects the local
OS via `/etc/os-release` `ID=` field (ubuntu/debian/alpine); (f)
registers a `localhost` node with `kind=localhost`, `os=<detected>`,
`addr=localhost:8443` if no localhost node exists yet. After
`orca init`, `orca doctor` MUST pass with zero FAILs. Idempotent:
re-running `orca init` is a no-op (or refresh) for already-provisioned
artifacts. Covers REQ-047, REQ-048, REQ-049.
- **P02 — Proxmox SSH join.** `orca node join --type proxmox --host
<addr> --user root --password <pw>` (password via flag or
`$ORCA_PROXMOX_PASSWORD`, **never persisted**) bootstraps a remote
Proxmox 8/9 host via `golang.org/x/crypto/ssh` (new direct dep).
Steps: (1) SSH password-auth; (2) generate or load orca's SSH
keypair (`~/.orca/orca_ssh_key` / `.pub`, 0600/0644); (3) deploy
pubkey to remote `~orca/.ssh/authorized_keys`; (4) create `orca`
user (config-overridable name via `--proxmox-user`, default `orca`);
(5) create PVE custom role `OrcaOperator` (config-overridable via
`--proxmox-role`) with privileges `VM.Audit`,
`Datastore.AllocateSpace`, `SDN.Use`; (6) assign role to `orca`
user on `/`; (7) drop `/etc/sudoers.d/orca` allowlist (`pct`, `qm`,
`pvesh`, `apt-get`, `dpkg` — no shell-escape commands); (8) record
node row `kind=proxmox`, `os=pve`, audit log. Idempotent re-run.
Covers REQ-050, REQ-051.
- **P03 — `doctor os` + `doctor proxmox`.** Extends `orca doctor`
with two new checks: `doctor os` re-runs `/etc/os-release` detection
and verifies it matches the stored localhost node row's `os` field
(drift = WARN); `doctor proxmox` iterates `kind=proxmox` nodes and
SSH-probes each with `pveversion` / `pvecmd status` (3s timeout per
peer per D-038 pattern), reporting PASS/WARN/FAIL per node. All
bootstrap + join actions emit structured audit-log entries. Covers
REQ-052.
- **P04 — Final review + ship + audit.** Milestone release.
The vision ("minimalist, offline-first, CLI-first orchestration
engine") is unchanged. v0.6 is a bootstrap-ergonomics + heterogeneous-
nodes milestone, not a direction change.