docs: golden 0.98.3 live — D.1b retired, drill B1/B5 fixed, backlog note resolved + evidence doc
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
This commit is contained in:
@@ -7,8 +7,10 @@
|
||||
>
|
||||
> **Drill-validated: 2026-07-03** on a clean-room nested PVE 9.2.2 VM (qemu/KVM on the build
|
||||
> server) — install → verify → app deploy → uninstall → residue-diff → reinstall, all executed
|
||||
> verbatim. Versions: script **v1.9.1**, agent **v0.62.0**, golden **v0.85.1** (controller updated
|
||||
> to 0.98.3 via D.1b). Evidence: `documentation/audits/DRILL-day0-cleanroom-2026-07-03.md`.
|
||||
> verbatim. Versions: script **v1.9.1**, agent **v0.63.0**, golden **v0.98.3** (controller current
|
||||
> on first boot — no manual update step). Evidence:
|
||||
> `documentation/audits/DRILL-day0-cleanroom-2026-07-03.md` (install/uninstall path) +
|
||||
> `documentation/audits/DRILL-golden-098-2026-07-03.md` (current-golden rebuild).
|
||||
>
|
||||
> Scope: a **shared** Proxmox box (the colleague's-box model) — a box that already runs, or will run,
|
||||
> non-Felhom guests. A dedicated box is the same procedure minus the sizing caution.
|
||||
@@ -69,16 +71,17 @@ On save the hub generates two credentials:
|
||||
Hub UI → **Configuration → Day-0 artifacts**. The manifest must vouch an **agent version** and a
|
||||
**golden version** (with their sha256s — auto-resolved from Gitea). The install script refuses to
|
||||
install anything the manifest doesn't vouch. If the vouched versions lag the fleet, bump them here
|
||||
first (dropdowns; the sha is fetched authoritatively).
|
||||
first (dropdowns; the sha is fetched authoritatively). Current drilled-known-good: agent
|
||||
**0.63.0** + golden **0.98.3**. Vouch a golden ≥ 0.98.3 — an older golden bakes a pre-floor
|
||||
controller and re-introduces the manual update step (Part F troubleshooting).
|
||||
|
||||
### A.4 Check the global controller-version floor
|
||||
|
||||
Hub UI → **Configuration**. Know the current `min_controller_version` floor, but understand its
|
||||
limit (drill-proven, OQ-2): a fresh box lands on the golden's baked-in controller (**v0.85.1**,
|
||||
which predates the floor-honoring code), so **the floor does NOT pull a fresh install up** — the
|
||||
one-time update in D.1b is the required step. Raising the floor still matters for keeping the box
|
||||
current afterwards. The structural fix — rebuilding + re-vouching the golden with a ≥ 0.86.0
|
||||
controller — is a recorded operator follow-up.
|
||||
Hub UI → **Configuration**. Know the current `min_controller_version` floor. With golden ≥ 0.98.3
|
||||
vouched (the structural fix for the old OQ-2 finding — drill-proven 2026-07-03), a fresh box lands
|
||||
on a **current, floor-honoring** controller and self-manages from first boot; the floor's job is
|
||||
keeping it current afterwards. Recommended (1 minute, records drift-protection): raise the global
|
||||
floor to the current controller version whenever the golden is rebuilt.
|
||||
|
||||
---
|
||||
|
||||
@@ -224,35 +227,29 @@ pct exec <VMID> -- curl -ksSo /dev/null -w '%{http_code}\n' \
|
||||
-H "Host: felhom.<CUSTOMER-DOMAIN>" https://127.0.0.1/ # want 200
|
||||
```
|
||||
|
||||
### D.1b One-time controller update (REQUIRED — do not skip)
|
||||
### D.1b Controller version check (one line — the old manual update step is RETIRED)
|
||||
|
||||
The golden bakes controller **v0.85.1**, which predates the v0.86.0 floor-honoring code — **a fresh
|
||||
install does NOT auto-update, regardless of the hub floor**. Bring it current once; from then on the
|
||||
floor mechanism manages it:
|
||||
The golden (≥ 0.98.3) bakes a **current, floor-honoring** controller — a fresh install is current on
|
||||
first boot and the hub floor manages it from here. Just verify:
|
||||
|
||||
```bash
|
||||
# 1. ONLY if the installed agent is OLDER than v0.63.0 (check: felhom-agent --version): restart it
|
||||
# first — pre-v0.63.0 agents 401 the update's swap call until restarted (fixed in v0.63.0 by
|
||||
# token reload-on-miss; which agent you got depends on what the hub Day-0 manifest vouched)
|
||||
systemctl restart felhom-agent
|
||||
|
||||
# 2. In the dashboard: Beállítások → "Frissítés" (update to latest), or equivalently:
|
||||
# controller version current on first boot; the floor manages it from here (want: update_available false)
|
||||
pct exec <VMID> -- curl -ksS -X POST -H "Host: felhom.<CUSTOMER-DOMAIN>" https://127.0.0.1/api/selfupdate/check
|
||||
pct exec <VMID> -- curl -ksS -X POST -H "Host: felhom.<CUSTOMER-DOMAIN>" https://127.0.0.1/api/selfupdate/update
|
||||
|
||||
# 3. Wait ~1 min, confirm the new version is running (image pull happens first, then an agent swap):
|
||||
pct exec <VMID> -- docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'
|
||||
```
|
||||
|
||||
If this reports the baked version as BEHIND (a newer controller shipped after the golden was baked),
|
||||
the same endpoint's `/api/selfupdate/update` — or the dashboard's Beállítások → "Frissítés" button —
|
||||
converges it; that is the normal self-update path, not an install-day requirement. (Installed from a
|
||||
golden older than 0.86.0? See Part F troubleshooting.)
|
||||
|
||||
### D.2 In the hub UI
|
||||
|
||||
- **Hosts**: the new host reports (status OK, fresh last-report timestamp).
|
||||
- The host's guest list shows `<VMID>` running.
|
||||
- **Capabilities**: 0 degraded. On a reduced-storage box (no `felhom-pbs`) the offsite-backup
|
||||
related capability is expected degraded — that is the documented go-live standard, not a fault.
|
||||
- The controller version shown for the guest matches what D.1b brought it to (the golden's baked
|
||||
0.85.1 does NOT self-converge — D.1b is the required manual step until the golden is rebuilt with
|
||||
a ≥ 0.86.0 controller).
|
||||
- The controller version shown for the guest is the golden's baked (current) version — it matches
|
||||
what D.1b's check reported.
|
||||
|
||||
### D.3 Customer-visible
|
||||
|
||||
@@ -311,8 +308,9 @@ roles/ACL/token/user, the pool (if empty), the install state file.
|
||||
| step 5 dies: "no git token in controller.yaml" | customer created without git credentials | Part A.2 — add `git.username`/`git.token`, regenerate config |
|
||||
| step 1: passphrase REJECTED (401) | typo / wrong customer | re-check with the hub UI's printed curl command |
|
||||
| step 8 fails: "CT <vmid> already exists" | vmid collision with a hub-invisible guest | pick from `pct list` + `qm list` (Part B); the agent destroys nothing on collision — re-run with a free vmid and `--resume` |
|
||||
| controller container missing in-guest after provision (docker ps empty) | pre-v1.9.1 script: the controller-bootstrap unit's boot-time condition lost the race with the bootstrap-mount attach | `pct reboot <VMID>` — the unit runs on the next boot (v1.9.1 does this reboot itself) |
|
||||
| self-update fails: "Agent swap request failed: HTTP 401" (or dashboard agent calls 401) | agent < v0.63.0: the daemon's token index missed a token minted by the provisioner after it started (FIXED in agent v0.63.0 — reload-on-miss) | `systemctl restart felhom-agent`, then retry (D.1b step 1; unnecessary from agent v0.63.0) |
|
||||
| controller container missing in-guest after provision (docker ps empty) | golden older than 0.98.3 (no baked path unit) + pre-v1.9.1 script: the controller-bootstrap unit's boot-time condition lost the race with the bootstrap-mount attach | `pct reboot <VMID>` — the unit runs on the next boot (v1.9.1 reboots itself; goldens ≥ 0.98.3 bake a path unit that starts the controller on the mount hot-plug, no reboot needed) |
|
||||
| fresh box runs an OLD controller and never self-updates (hub floor ignored) | a golden **older than 0.86.0** was vouched in the Day-0 manifest — its baked controller predates the floor-honoring code | one-time manual update (the retired old D.1b): dashboard Beállítások → "Frissítés", or `POST /api/selfupdate/check` + `/api/selfupdate/update` via the traefik Host-header probe; if the agent is < v0.63.0, `systemctl restart felhom-agent` FIRST (pre-v0.63.0 agents 401 the swap call). Structural fix: re-vouch a golden ≥ 0.98.3 (A.3) |
|
||||
| self-update fails: "Agent swap request failed: HTTP 401" (or dashboard agent calls 401) | agent < v0.63.0: the daemon's token index missed a token minted by the provisioner after it started (FIXED in agent v0.63.0 — reload-on-miss) | `systemctl restart felhom-agent`, then retry (unnecessary from agent v0.63.0) |
|
||||
| `local-lvm free < 120 GiB` warning | small/shared box | proceed only if you sized the grows deliberately; otherwise free space first |
|
||||
| cloudflared restarting in-guest | bad/missing tunnel token | re-check A.1/A.2 token, regenerate config, `docker restart cloudflared` in-guest |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user