From ce26c9d6461e6d566eacea8b7e1e7a90fa58178e Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Wed, 1 Jul 2026 08:20:27 +0200 Subject: [PATCH] docs: REPORT for host-install v1.4.0 (CPU/RAM cap passthrough; manifest follow-up) Co-Authored-By: Claude Opus 4.8 (1M context) --- REPORT.md | 113 +++++++++++++++++++++++------------------------------- 1 file changed, 49 insertions(+), 64 deletions(-) diff --git a/REPORT.md b/REPORT.md index c44a88f..51280fa 100644 --- a/REPORT.md +++ b/REPORT.md @@ -4,96 +4,81 @@ --- -# REPORT — `felhom-host-install.sh --uninstall` (clean revert) + pre-flight guards (host-install v1.3.0) +# REPORT — appliance CPU/RAM cap passthrough (`--cores` / `--memory`) (host-install v1.4.0) **Date:** 2026-07-01 · **Repo:** `felhom.eu` (`scripts/` only) -Colleague-safety batch **#1 (`--uninstall`) + #2 (pre-flight guards)**. Script-only. A first-class, -guarded local host-teardown mode so an operator can cleanly back out of a trial install, plus three -provision pre-flight guards. Specced, built, and validated **dry-run-only** (the live `--uninstall` is a -supervised step and was deliberately NOT run — see the STOP list). +Colleague-safety batch **#3** (host-install half; the cap mechanism is agent **v0.52.0**, a separate +repo/task). Adds optional `--cores`/`--memory` passthrough so an operator can cap the provisioned +appliance guest and keep it from pressuring a colleague's existing guests on a shared production host. ## 1. Confirmed baseline | Repo | `main` @ commit | Current | → Target | |------|-----------------|---------|----------| -| felhom.eu (`scripts/felhom-host-install.sh`) | `83c4f7f7` | script **v1.2.0** | **v1.3.0** | +| felhom.eu (`scripts/felhom-host-install.sh`) | `710afb0` | script **v1.3.0** | **v1.4.0** | -No agent/controller/hub change in this task. +## 2. Files changed + commit -## 2. Files changed - -- `scripts/felhom-host-install.sh` (v1.2.0 → **v1.3.0**) — the only code file. -- `scripts/CHANGELOG.md` — v1.3.0 entry (newest on top; this is where the v1.2.0 entry lives). +- `scripts/felhom-host-install.sh` (v1.3.0 → **v1.4.0**). +- `scripts/CHANGELOG.md` — v1.4.0 entry. - `REPORT.md` — this file (overwritten). +- Commit **`f7905b7`** on `main` (parent `710afb0`). -## 3. Commit hash(es) +## 3. What was implemented -- `6db68f4` on `main` (parent `83c4f7f`). +- **`--cores N` / `--memory M` (MiB)** — new vars `CPU_CORES`/`MEM_MIB`; arg-parse entries; `usage()` + header gains an "Appliance cap (optional)" group (needs agent ≥ v0.52.0; `0`/unset = golden default). +- **Conditional passthrough** — `step_provision` builds a `cap_args` array (`-cores`/`-memory` appended + only when set) and passes it to BOTH the dry-run log and the real agent `--selftest=provision` call. + Never sent unset, so an agent < v0.52.0 never sees an unknown flag. +- **Pre-flight sanity WARN (soft, provision only)** — if `--cores` > host `nproc` or `--memory` > host + `MemTotal`, `log_warn`; never `die`. -## 4. What was implemented +## 4. Green gate -**Part 1 — install state records vmid + customer.** New `_state_put KEY VALUE` / `_state_get KEY` -helpers (python3, dry-run-guarded like `_state_mark`, `completed[]` shape untouched). `step_preflight` -now records `customer_id`; `step_provision` records `provisioned_vmid` on success (dry-run logs only). +- `bash -n scripts/felhom-host-install.sh` → OK (locally + on felhom-pve). +- `shellcheck v0.10.0`: v1.4.0 = **2× SC2015 (info)** at lines 1160 & 1170 — both the *pre-existing* + `step_verify` `A && B || C` lines, unchanged. **0 new warnings** vs. the v1.3.0 baseline. -**Part 2 — `--uninstall` mode** (early top-level dispatch, root-required, no `--customer-id`, no hub -contact, no passphrase). `run_uninstall` reverses install order: **guest → agent(unit+.bak / sudoers / -binary+.bak / state dir / user) → pveum(ACL user, ACL token, token, user, role) → golden(opt-in) → -state file.** Every mutation via `run()` (dry-run prints, executes nothing). Guards: ours-check on the -`/etc/felhom-bootstrap` bind mount (matched by the constant guest *path*, not a slot), typed vmid -confirmation (`/dev/tty`, skipped only in dry-run), other-Felhom-guests safe-skip (keeps host-level in -place unless `--force`), state-mismatch `--force` gate, and idempotent tolerate-absent on every object. -`--remove-golden` opt-in deletes the golden vzdump (`pvesm free`). Never removes the `sudo` package; -never contacts the hub. New helper `felhom_guests()` enumerates Felhom guests by the bootstrap mount. - -**Part 3 — pre-flight guards** (all inside `step_preflight`, before any mutation → fire under dry-run): -multi-node guard (`die` unless `--node` explicit via new `NODE_EXPLICIT`; no-op single-node / under -`--skip-provision`), archive-storage-exists guard (`pvesm status --storage`; no-op under -`--skip-provision`), RAM floor WARN (`MemAvailable < 2048 MiB`, never fatal). - -Confirmed the PVE 9 ACL-delete syntax live before wiring it: -`pveum acl delete --users|--tokens --roles `. - -## 5. Green gate — `bash -n` + `shellcheck` - -- `bash -n scripts/felhom-host-install.sh` → **OK** (locally + on felhom-pve). -- `shellcheck v0.10.0` (fetched static binary on the build server; shellcheck isn't installed on any - box): **HEAD v1.2.0 baseline = 2× SC2015 (info)**; **v1.3.0 = 2× SC2015 (info)** at lines 1128 & 1138 - — both in the *pre-existing* `step_verify` (`A && B || C`), untouched by this task. **0 new warnings.** - -## 6. Tests → §7 mapping (dry-run transcripts / read-only live checks on felhom-pve, single-node, live guest 9201) +## 5. Tests → §7 mapping (dry-run transcripts on felhom-pve; real demo customer via 0600 passphrase-file, free vmid 9300) | # | Scenario | Result | |---|----------|--------| -| T-A | full clean-uninstall plan (`--uninstall --vmid 9201 --dry-run`) | **PASS** — ours-check passes, prints `pct config 9201`, would-prompt for typed confirm, then the full plan: `pct stop/destroy 9201` → agent removal (unit + all `.bak-*`, sudoers, binary + all `.bak-*`, `rm -rf /var/lib/felhom-agent`, `userdel`) → `pveum acl delete` (user, then token) → token remove → user delete → **role delete last** → golden skipped → state file rm. All `[DRY-RUN]`. `sudo` package NOT touched; hub note printed. | -| T-B | other-guests detector | **PASS** — `felhom_guests()` enumeration prints only `9201` (only Felhom guest on the host). Skip-branch code-reviewed (2nd Felhom guest not available live). | -| T-C | not-ours refusal (**red-proof**) | **PASS** — `--uninstall --vmid 9001 --dry-run` (9001 exists, no bootstrap mount) → `die "vmid 9001 does not look like a Felhom-provisioned guest … Refusing to destroy. Pass --force to override."`, exit 1, dies before any `run()`. Nonexistent id `987654` → safe refusal ("absent and is not the recorded provisioned_vmid … --force"). | -| T-D | multi-node guard | **PASS (single-node)** — `node: demo-felhom (auto)`, guard is a no-op on the 1-node host; multi-node `die` code-reviewed. Live multi-node validation deferred (see STOP). | -| T-E | storage / RAM guards | **PASS** — `--dry-run --archive-storage nonesuch` → `die "archive storage 'nonesuch' not found (pvesm status)…"` before the passphrase prompt; normal dry-run prints the RAM line (`free RAM: ~12251 MiB`; the `<2048` WARN branch is code-reviewed — the box has 12 GiB free). | -| T-F | dry-run executes nothing | **PASS** — after all dry-runs: `pct status 9201` = running, `felhom-agent` active, binary present, `pveum` user + role present, `state.json` unchanged (no `provisioned_vmid` added — dry-run writes nothing). | -| Part 1 | `_state_put`/`_state_get` round-trip | **PASS** — isolated temp-file test: writes top-level `customer_id`/`provisioned_vmid`, preserves `completed[]`, reads both back. | +| T-C | script passthrough | **PASS** — `--cores 2 --memory 4096 --dry-run` → provision command shows `… -sysdata-grow 42 -cores 2 -memory 4096`. | +| T-C⁻ | no cap → flags absent | **PASS** — without `--cores`/`--memory` the provision command ends `… -sysdata-grow 42 ` with NEITHER flag. | +| T-D | sanity WARN | **PASS** — `--cores 64 --memory 65536 --dry-run` (host = 4 cores / ~15771 MiB) → two WARN lines: "requested cap (64 cores) exceeds host cores (4)…" and "requested cap (65536 MiB) exceeds host RAM (~15771 MiB)…"; does not die. | -## 7. Served-copy version check (after push) +(T-A cap-pre-boot + T-B omit-when-zero are the AGENT side — see `felhom-agent/REPORT.md`: live scratch +bring-up on vmid 9300 showed `cores:1`/`memory:1024`, then destroyed; `TestBuildBringUpConfig_ResourceCaps` ++ red-proof.) + +## 6. Served-copy version check ``` curl -fsSL https://felhom.eu/scripts/felhom-host-install.sh | grep SCRIPT_VERSION -# expect: SCRIPT_VERSION="1.3.0" ``` -→ **`SCRIPT_VERSION="1.3.0"`** (served copy confirmed v1.3.0 ~1 min after push). +→ **`SCRIPT_VERSION="1.4.0"`** (served copy confirmed ~1 min after push). -## 8. NOT yet live-validated — awaiting a supervised run +## 7. Hub artifact manifest status — REQUIRED FOLLOW-UP -- A **real live `--uninstall`** (actual guest destroy + `pveum` role/user/token/ACL removal + `userdel` - + state wipe). Deliberately not run per the TASK STOP — do it on the colleague's box or a throwaway - scratch guest, never the demo guest 9201. -- The **multi-node guard** on an actual 2+-node cluster (felhom-pve is single-node). -- The other-Felhom-guests safe-skip branch with a second live Felhom guest present. +The `--cores`/`--memory` passthrough depends on a fresh install fetching **agent ≥ v0.52.0**. Status: +- ✅ Agent v0.52.0 published to Gitea (`admin/generic/felhom-agent/0.52.0/felhom-agent`, sha + `5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb`, round-trip verified). +- ✅ Hub deploy env fallback bumped to `ARTIFACT_AGENT_VERSION=0.52.0` + new sha (seeds an empty manifest). +- ❌ **The served manifest still returns agent 0.43.0** — the hub seeds env only into an *empty* DB field + and the stored value (0.43.0) wins. The manifest can only be changed via the **password-gated operator + UI** (Configs → Day-0 artifacts), which is out of CC's reach. **An operator must set the artifact + manifest to agent 0.52.0 / sha 5bfc690c421b7799f4e0640f13559c41e5933ee60962bf80471eca7eae0e94cb before + the colleague uses `--cores`/`--memory` on a fresh install.** (Details in `felhom-agent/REPORT.md` §6.) + +## 8. NOT yet live-validated — awaiting supervised run + +- A **capped real customer provision** end-to-end via the script (`--cores`/`--memory` without + `--dry-run` against a real customer/guest) — the supervised step on the colleague's box. ## 9. Observations (noticed, NOT acted on) -- In `--dry-run`, `run_uninstall` prints `[OK] guest destroyed` after the `[DRY-RUN] pct destroy` - lines; the trailing `[DRY-RUN]: nothing above was actually executed.` clarifies it, and this mirrors - the existing dry-run success-logging pattern — left as-is (minimal change). -- Colleague-safety batch items #3 (CPU/mem cap, agent-side) and #4 (pool-scoped ACL) are separate specs; - not touched here. +- The hub artifact manifest was already stale (agent 0.43.0) before this task; fresh installs fetched an + old agent regardless of this change. The operator manifest bump in §7 also clears that lag. +- Spec 2's sibling items #4 (pool-scoped ACL) is a separate later task; not touched here.