admin/felhom.eu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: REPORT for host-install v1.4.0 (CPU/RAM cap passthrough; manifest follow-up)

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
authentik Default Admin
2026-07-01 08:20:27 +02:00
parent f7905b78b5
commit ce26c9d646
1 changed files with 49 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
REPORT.md
+49 -64
View File
@@ -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 <path> --users|--tokens <x> --roles <role>`.
## 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 <vmid> 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.