From 7639ab5c4b5f594ab1dcfc7d49d8c3bd4d23a155 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Wed, 1 Jul 2026 12:32:41 +0200 Subject: [PATCH] v0.53.0: restore guests INTO the felhom pool (pool-scoped-ACL enabler) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RestoreLXCOptions.Pool → pct restore --pool (omit-when-empty). New reconcile.DefaultPool="felhom"; BringUpSpec.Pool threaded to the bring-up restore; BOTH restore sites pool the guest (provision/DR via spec.Pool set to DefaultPool by the CLI; restore-test scratch via DefaultPool = SPIKE residual #2). No agent ACL change (ships in host-install v1.6.0); the pool param is inert until the token has Pool.Allocate + the pool exists, so publishing is safe ahead of the coordinated swap. Tests + red-proofs; go build/vet/test clean. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 25 +++++++++++++++++++ README.md | 7 ++++++ cmd/felhom-agent/main.go | 4 ++- internal/proxmox/mutate.go | 8 ++++++ internal/proxmox/restore_test.go | 39 ++++++++++++++++++++++++++++++ internal/reconcile/bringup.go | 9 ++++++- internal/reconcile/bringup_test.go | 36 +++++++++++++++++++++++++++ internal/reconcile/restoretest.go | 4 ++- 8 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 internal/proxmox/restore_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index efff7e8..dfeed51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,28 @@ +## v0.53.0 — restore guests INTO the felhom pool (pool-scoped-ACL enabler) (2026-07-01) + +Colleague-safety batch #4 phase b (agent half). Enables the agent token to be scoped from `/` to +`/pool/felhom` + `/storage/` (real blast-radius containment on a shared host) by making every +restore allocate the guest INTO the pool — the only way a fresh vmid authorizes under a pool-scoped +token. Grounded by `felhom.eu/documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md` (PASS). + +- **`internal/proxmox/mutate.go`:** `RestoreLXCOptions` gains `Pool string`; `RestoreLXC` sends + `pool=

` only when non-empty (`pct restore --pool`). Omit-when-empty (a broad-token restore needs + no pool) — unit-tested + red-proofed. +- **`internal/reconcile`:** new `const DefaultPool = "felhom"` (single source of truth); `BringUpSpec` + gains `Pool`, threaded to the bring-up restore. **Both restore sites** now pool the guest: the + provision/DR bring-up (`Pool: spec.Pool`, set to `DefaultPool` by the CLI) AND the **restore-test** + scratch guest (`Pool: DefaultPool`) — the latter closes SPIKE residual #2 (a pool-scoped token would + otherwise 403 on the out-of-pool scratch guest). +- **`cmd/felhom-agent/main.go`:** both `BringUpSpec` literals (bring-up/DR + provision) set + `Pool: reconcile.DefaultPool`. +- **No ACL/priv change in the agent** — that ships in the host-install script (v1.6.0). The pool param + is INERT until the token is granted `Pool.Allocate` at `/pool/felhom` and the pool exists; publishing + is therefore safe ahead of the coordinated ACL swap. +- New tests: `proxmox.TestRestoreLXC_PoolParam` (set → `pool=felhom`; empty → omitted), + `reconcile.TestRestoreSitesUsePool` (both restore sites carry `DefaultPool`). Both red-proofed + (unconditional `Set` → omit test fails; drop either site's `Pool` → both-sites test fails). `go + build`/`vet`/`test ./...` clean. + ## v0.52.0 — operator-opt-in CPU/RAM cap for the provisioned guest (`-cores` / `-memory`) (2026-07-01) Colleague-safety batch #3. So a trial appliance guest on a colleague's SHARED production Proxmox does diff --git a/README.md b/README.md index f92cd6b..0afd97e 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,13 @@ so cleanly if the token/endpoint isn't configured. into the SAME pre-start config PUT as the identity reset (via `BringUpSpec.Cores/MemoryMB`), so the guest never boots uncapped — useful when the appliance shares a host with other guests. +**Pool-scoped restore (v0.53.0):** every restore (provision bring-up, DR, and restore-test) allocates +the guest INTO the `felhom` PVE pool (`reconcile.DefaultPool`; `RestoreLXCOptions.Pool` → `pct restore +--pool`). This is what lets the agent token be scoped to `/pool/felhom` + `/storage/` instead +of `/` (blast-radius containment on a shared host) — the restore is how a fresh vmid is allocated under +that scoped token (`VM.Allocate`+`Pool.Allocate` at `/pool/felhom`). Layout + validation: +`felhom.eu/documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md`. + ## Process model Native Go binary, systemd service, **non-root** `felhom-agent` service user holding the scoped token, diff --git a/cmd/felhom-agent/main.go b/cmd/felhom-agent/main.go index d6cee2c..9a2cc9c 100644 --- a/cmd/felhom-agent/main.go +++ b/cmd/felhom-agent/main.go @@ -45,7 +45,7 @@ import ( // version is the agent version. Overridable at build time with // -ldflags "-X main.version="; defaults to the in-repo CHANGELOG version. -var version = "0.52.0" +var version = "0.53.0" // runGuestHook is the PVE pre-start hook body (`felhom-agent guest-hook `). On the // pre-start phase it creates placeholder dirs for any absent bind-mount source so the guest always boots @@ -1216,6 +1216,7 @@ func runSelftestBringUp(ctx context.Context, cfg config.Config, logger *slog.Log spec := reconcile.BringUpSpec{ Mode: bmode, Archive: archive, VMID: vmid, RestoreStorage: cfg.Backup.RestoreStorage, Hostname: hostname, KeepMAC: bmode == reconcile.ModeDRGuestLoss, + Pool: reconcile.DefaultPool, // restore into the felhom pool (both provision + DR); required under the scoped token Cores: sizing.Cores, MemoryMB: sizing.MemoryMB, RootfsGrowGB: sizing.RootfsGrowGB, DataVolGrowGB: sizing.DataVolGrowGB, DataVolMount: sizing.DataVolMount, SysDataGrowGB: sizing.SysDataGrowGB, SysDataMount: sizing.SysDataMount, @@ -1370,6 +1371,7 @@ func runSelftestProvision(ctx context.Context, cfg config.Config, logger *slog.L res := engine.RunBringUp(ctx, reconcile.BringUpSpec{ Mode: reconcile.ModeProvision, Archive: a.archive, VMID: a.vmid, RestoreStorage: cfg.Backup.RestoreStorage, Hostname: hostname, + Pool: reconcile.DefaultPool, // provision into the felhom pool; required under the scoped token Cores: a.sizing.Cores, MemoryMB: a.sizing.MemoryMB, RootfsGrowGB: a.sizing.RootfsGrowGB, DataVolGrowGB: a.sizing.DataVolGrowGB, DataVolMount: a.sizing.DataVolMount, SysDataGrowGB: a.sizing.SysDataGrowGB, SysDataMount: a.sizing.SysDataMount, diff --git a/internal/proxmox/mutate.go b/internal/proxmox/mutate.go index 501b0ac..5b67071 100644 --- a/internal/proxmox/mutate.go +++ b/internal/proxmox/mutate.go @@ -34,6 +34,11 @@ type RestoreLXCOptions struct { Archive string // source archive volid, e.g. "local:backup/vzdump-lxc-9001-...tar.zst" Storage string // target storage for the rootfs, e.g. "local-lvm" Force bool // overwrite an existing VMID (destructive — caller must have authority) + // Pool allocates the restored guest INTO a PVE pool (pct restore --pool). "" = no pool. Under a + // pool-scoped token this is REQUIRED for the restore to authorize (VM.Allocate + Pool.Allocate are + // granted at /pool/, not /), and it makes the guest reachable by the scoped token afterwards + // (SPIKE-pool-scoped-acl-2026-07-01). Empty is valid — a broad-token restore needs no pool. + Pool string // MountOverrides overrides specific mountpoints at restore time (mpN -> full value, e.g. // "local-lvm:1,mp=/data,backup=0"). A restore param takes precedence over the archive's own // mpN. The restore-test uses this to neutralize a SOURCE host bind-mount mountpoint (slice-10 @@ -59,6 +64,9 @@ func (c *Client) RestoreLXC(ctx context.Context, opts RestoreLXCOptions) (string if opts.Force { v.Set("force", "1") } + if opts.Pool != "" { + v.Set("pool", opts.Pool) // allocate into the pool (pool-scoped token needs this — see RestoreLXCOptions.Pool) + } for k, val := range opts.MountOverrides { v.Set(k, val) // e.g. mp0 -> "local-lvm:1,mp=/data,backup=0" (overrides the archive's mp0) } diff --git a/internal/proxmox/restore_test.go b/internal/proxmox/restore_test.go new file mode 100644 index 0000000..afb9cce --- /dev/null +++ b/internal/proxmox/restore_test.go @@ -0,0 +1,39 @@ +package proxmox + +import ( + "context" + "io" + "net/http" + "strings" + "testing" +) + +// RestoreLXC sends pool= only when Pool is set. Under a pool-scoped token the restore MUST carry +// pool=felhom (else VM.Allocate/Pool.Allocate 403); with Pool empty it MUST be omitted (a naive +// unconditional Set would send an empty pool= — omit-when-empty is the guarantee). +func TestRestoreLXC_PoolParam(t *testing.T) { + var body string + d := &mockDoer{fn: func(r *http.Request) (*http.Response, error) { + b, _ := io.ReadAll(r.Body) + body = string(b) + return jsonResp(200, `{"data":"`+testUPID+`"}`), nil + }} + c := newTestClient(d) + ctx := context.Background() + + // Pool set → pool=felhom present in the POST body. + if _, err := c.RestoreLXC(ctx, RestoreLXCOptions{VMID: 9100, Archive: "local:backup/a.tar.zst", Storage: "local-lvm", Pool: "felhom"}); err != nil { + t.Fatalf("RestoreLXC(Pool): %v", err) + } + if !strings.Contains(body, "pool=felhom") { + t.Errorf("Pool set: expected pool=felhom in body, got %q", body) + } + + // Pool empty → NO pool key at all (omit-when-empty). + if _, err := c.RestoreLXC(ctx, RestoreLXCOptions{VMID: 9100, Archive: "local:backup/a.tar.zst", Storage: "local-lvm"}); err != nil { + t.Fatalf("RestoreLXC(no Pool): %v", err) + } + if strings.Contains(body, "pool=") { + t.Errorf("Pool empty: pool key must be ABSENT, got %q", body) + } +} diff --git a/internal/reconcile/bringup.go b/internal/reconcile/bringup.go index 3c49933..711609f 100644 --- a/internal/reconcile/bringup.go +++ b/internal/reconcile/bringup.go @@ -43,6 +43,12 @@ const bringUpKind = "bring_up" // DefaultDataVolMount is the mpN slot the golden bakes the Docker-data volume (/var/lib/docker) at. const DefaultDataVolMount = "mp0" +// DefaultPool is the PVE pool every Felhom-managed guest is restored INTO. Under the pool-scoped agent +// token, restore-into-pool is how a fresh vmid gets allocated (VM.Allocate + Pool.Allocate at +// /pool/felhom) and how the guest becomes reachable by the scoped token (SPIKE-pool-scoped-acl-2026-07-01). +// Single source of truth for both restore sites (provision bring-up + restore-test). +const DefaultPool = "felhom" + // DefaultSysDataMount is the mpN slot the golden bakes the SSD user-data volume (/mnt/sys_drive) at. // This is the controller's system_data_path; provision grows it (SysDataGrowGB) like the Docker-data // volume. mp1 is the natural next bring-up slot (mp8/mp9 are added by the provision back-half). @@ -76,6 +82,7 @@ type BringUpSpec struct { VMID int // caller-provided target VMID (NOT the restore-test band / 9999) RestoreStorage string // rootfs target storage Hostname string // hostname to set (provision); ignored for DR (continuity) + Pool string // restore the guest INTO this PVE pool ("" = none); required under a pool-scoped token Cores int // 0 = leave as restored MemoryMB int // 0 = leave as restored RootfsGrowGB int // optional grow-only rootfs resize (0 = skip) @@ -200,7 +207,7 @@ func (e *Engine) runBringUp(ctx context.Context, spec BringUpSpec, res *BringUpR // 1. Restore archive → VMID (token-covered ClassCreate; keyctl preserved — phase3 + spike). upid, err := e.api.RestoreLXC(ctx, proxmox.RestoreLXCOptions{ - VMID: spec.VMID, Archive: spec.Archive, Storage: spec.RestoreStorage, + VMID: spec.VMID, Archive: spec.Archive, Storage: spec.RestoreStorage, Pool: spec.Pool, }) if err != nil { res.Err = fmt.Errorf("reconcile: bring-up restore: %w", err) diff --git a/internal/reconcile/bringup_test.go b/internal/reconcile/bringup_test.go index 2835ba8..5c9c03e 100644 --- a/internal/reconcile/bringup_test.go +++ b/internal/reconcile/bringup_test.go @@ -119,6 +119,42 @@ func TestBuildBringUpConfig_ResourceCaps(t *testing.T) { } } +// Both restore sites allocate the guest INTO the felhom pool (SPIKE 3b): the provision bring-up +// threads spec.Pool, and the restore-test hardcodes DefaultPool — else a pool-scoped token 403s on +// the created guest's config/start/destroy. Asserts via the fakeAPI's captured RestoreLXCOptions. +func TestRestoreSitesUsePool(t *testing.T) { + // provision bring-up: spec.Pool must flow to the restore + const vmid = 8060 + api := &fakeAPI{cfg: map[int]proxmox.GuestConfig{vmid: scratchCfg()}} + e, _, q := newEngine(t, api, EmptyProvider{}) + defer q.Close() + res := e.RunBringUp(context.Background(), BringUpSpec{ + Mode: ModeProvision, Archive: "local:backup/g.tar.zst", VMID: vmid, + RestoreStorage: "local-lvm", Pool: DefaultPool, + }) + if res.Err != nil || !res.Pass { + t.Fatalf("bring-up must pass: %+v", res) + } + if len(api.restores) != 1 || api.restores[0].Pool != DefaultPool { + t.Fatalf("provision restore must set Pool=%q, got %+v", DefaultPool, api.restores) + } + + // restore-test: the scratch restore hardcodes DefaultPool + api2 := &fakeAPI{cfg: map[int]proxmox.GuestConfig{990000: scratchCfg()}} + e2, _, q2 := newEngine(t, api2, EmptyProvider{}) + defer q2.Close() + rt := e2.RunRestoreTest(context.Background(), RestoreTestSpec{ + Archive: "local:backup/x.tar.zst", RestoreStorage: "local-lvm", + ScratchMin: 990000, ScratchMax: 990009, SourceTier: "local", + }) + if rt.Err != nil || !rt.Pass { + t.Fatalf("restore-test must pass: %+v", rt) + } + if len(api2.restores) != 1 || api2.restores[0].Pool != DefaultPool { + t.Fatalf("restore-test restore must set Pool=%q, got %+v", DefaultPool, api2.restores) + } +} + // The golden-carried Docker-data volume is grown via a SEPARATE resize on its mpN slot (B4), // alongside (but distinct from) the rootfs grow. func TestRunBringUp_StorageSplit_DataVolGrow(t *testing.T) { diff --git a/internal/reconcile/restoretest.go b/internal/reconcile/restoretest.go index 4de2cb6..7d8fd9d 100644 --- a/internal/reconcile/restoretest.go +++ b/internal/reconcile/restoretest.go @@ -192,7 +192,9 @@ func (e *Engine) runScratchTest(ctx context.Context, vmid int, spec RestoreTestS } } upid, err := e.api.RestoreLXC(ctx, proxmox.RestoreLXCOptions{ - VMID: vmid, Archive: spec.Archive, Storage: spec.RestoreStorage, MountOverrides: mountOverrides, + // Pool=DefaultPool so the scratch guest is created INTO the felhom pool — else a pool-scoped + // token 403s on the scratch guest's config/start/destroy (SPIKE residual #2). + VMID: vmid, Archive: spec.Archive, Storage: spec.RestoreStorage, MountOverrides: mountOverrides, Pool: DefaultPool, }) if err != nil { res.Err = fmt.Errorf("reconcile: restore-test restore: %w", err)