R-812 option A: the Proxmox package lane (layer pve) + the /etc/pve write gate

The wrapper gains layer "pve" (slow lane): the host's Proxmox userspace packages only — origin "Proxmox Debian Repository", never a kernel / boot / firmware / microcode name (R14), no removal, no undo, a new package only from an allow-list; authority = a signed os_pve_step or the root-owned ring-0 mark. The night leg runs it in ring 0 after a healthy host step; ring 1 only by a signed job (PVEStepExecutor). While it runs, the agent's own /etc/pve writes (every non-GET API call, pct config verbs, pvesm, pveum, felhom-pbs-apply) wait on internal/pvegate. Health = the host rule + unchanged container ids + pveversion reads the installed pve-manager. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-10-07 10:07:41 +02:00
parent ac90169a5d
commit ce1a4b4758
17 changed files with 990 additions and 41 deletions
@@ -20,6 +20,7 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
+	"regexp"
 	"sort"
 	"strings"
 	"sync"
@@ -27,6 +28,7 @@ import (

 	"gitea.dooplex.hu/admin/felhom-agent/internal/hub"
 	"gitea.dooplex.hu/admin/felhom-agent/internal/proxmox"
+	"gitea.dooplex.hu/admin/felhom-agent/internal/pvegate"
 )

 // WrapperPath is the pinned sudoers vector (configs/felhom-agent.sudoers FELHOM_OSAPPLY).
@@ -40,8 +42,21 @@ const (
 	LayerGuest  = "guest"
 	LayerHost   = "host"
 	LayerDocker = "docker" // the guest's Docker engine set — slow lane (`11` §5.8)
+	// LayerPVE is the HOST's Proxmox userspace packages — slow lane (R-812 option A, `09` §3 decision 163, `11` §5.10):
+	// ring 0 in the night leg after a healthy host step, ring 1 only inside a signed os_pve_step. Never a kernel.
+	LayerPVE = "pve"
 )

+// PVEOrigin is the origin apt prints for download.proxmox.com (the wrapper's PVE_ORIGIN); InstalledPVEOrigin is how
+// the wrapper's inventory names the same source.
+const (
+	PVEOrigin          = "Proxmox Debian Repository"
+	InstalledPVEOrigin = "Proxmox"
+)
+
+// hostSlowRE mirrors the wrapper's HOST_SLOW_RE: kernel, boot, firmware and microcode names never ride the pve lane.
+var hostSlowRE = regexp.MustCompile(`^(linux-(image|headers|kbuild|modules|base)|proxmox-kernel|proxmox-default-kernel|pve-kernel|pve-firmware|firmware-|grub|shim|systemd-boot|intel-microcode|amd64-microcode|efibootmgr)`)
+
 // DockerNames are the six packages of the Docker engine set (the wrapper's DOCKER_NAMES).
 var DockerNames = map[string]bool{"containerd.io": true, "docker-buildx-plugin": true, "docker-ce": true,
 	"docker-ce-cli": true, "docker-ce-rootless-extras": true, "docker-compose-plugin": true}
@@ -109,6 +124,8 @@ type WrapperReport struct {
 	// OOMCheck (R-528, `09` decision 157): the docker layer's memory-kill check, {result, oom_killed, oom_event,
 	// exit_code, image, detail}. Carried to the hub UNCHANGED; the agent never reads it.
 	OOMCheck json.RawMessage `json:"oom_check"`
+	// PVEManager: the pve layer — pveversion's pve-manager version after the step ("unknown" = unreadable).
+	PVEManager string `json:"pve_manager"`
 	// R-868 (v0.144.0): the agent's ids, echoed from the plan, so a report kept on disk can be sent without the
 	// agent process that started the pass. ReleaseID / VMID were always in the report.
 	RunID     string `json:"run_id"`
@@ -149,6 +166,8 @@ type Report struct {
 	// OOMCheck: docker layer — the wrapper's oom_check object, byte-for-byte (R-528; the hub decides approval on it).
 	// Pinned by TestDocker_OOMCheckReachesTheHubUnchanged and TestR868_KeptCopyCarriesTheOOMCheck.
 	OOMCheck json.RawMessage `json:"oom_check,omitempty"`
+	// PVEManager: pve layer — pve-manager's version after the step (the hub's System page; R-812 option A).
+	PVEManager string `json:"pve_manager,omitempty"`

 	unsent string // R-868: the wrapper's kept copy of this pass's report — deleted once the hub has it
 }
@@ -386,6 +405,36 @@ func EngineOf(pkgVersion string) string {
 	return v
 }

+// PVEHealthVerdict is THE Proxmox-package-step health rule (R-812 option A; pinned by TestPVEHealthVerdict): the host
+// rule (every host service active, the guest running and healthy, the tunnel running), plus every container running at
+// the start still runs as the SAME container (a Proxmox step must not restart the household's apps), plus pveversion
+// now reports the pve-manager the step installed (wantPVE "" = pve-manager was not in the step).
+func PVEHealthVerdict(before, after *Health, tunnel, wantPVE, gotPVE string) (bool, string) {
+	if ok, why := HostHealthVerdict(before, after, tunnel); !ok {
+		return false, why
+	}
+	if before != nil && before.Guest != nil && after.Guest != nil {
+		names := make([]string, 0, len(before.Guest.Containers))
+		for n := range before.Guest.Containers {
+			names = append(names, n)
+		}
+		sort.Strings(names)
+		for _, n := range names {
+			b := before.Guest.Containers[n]
+			if b.State != "running" || b.ID == "" {
+				continue
+			}
+			if a := after.Guest.Containers[n]; a.ID != b.ID {
+				return false, n + " is a new container (id changed) — the Proxmox step restarted the household's app"
+			}
+		}
+	}
+	if wantPVE != "" && gotPVE != wantPVE {
+		return false, "pveversion reads pve-manager " + gotPVE + ", not " + wantPVE
+	}
+	return true, ""
+}
+
 // DockerHealthVerdict is THE Docker-step health rule (`11` §5.8; pinned by TestDockerHealthVerdict): the guest rule,
 // plus every container running at the start still runs as the SAME container (same id — a changed id means the
 // household's apps restarted, which `live-restore` exists to prevent), plus the engine now reports the version the step
@@ -451,7 +500,7 @@ func (l *Leg) call(ctx context.Context, runID string, plan map[string]any) (Wrap

 // Pass is one leg's reports; an empty Layer means the step did not run.
 type Pass struct {
-	Guest, Host, Docker Report
+	Guest, Host, Docker, PVE Report
 }

 // Run is one pass: the guest layer, then (on an appliance, after a good guest step) the host layer, then (ring 0
@@ -479,13 +528,44 @@ func (l *Leg) Run(ctx context.Context, vmid int, trigger string) Pass {
 		if err := l.EnsureLiveRestore(ctx, g.RunID, vmid); err != nil {
 			p.Docker = l.finish(ctx, lg, Report{RunID: g.RunID, Layer: LayerDocker, Trigger: trigger, Ring: 0, VMID: vmid,
 				Mode: "apply", Outcome: "failed", HealthReason: "live-restore could not be turned on: " + err.Error()})
-			return p
+		} else {
+			p.Docker = l.runLayer(ctx, g.RunID, LayerDocker, vmid, trigger, blk, dockerOpts{})
 		}
-		p.Docker = l.runLayer(ctx, g.RunID, LayerDocker, vmid, trigger, blk, dockerOpts{})
+	}
+	// R-812 option A: the Proxmox package step — ring 0, an appliance, after a HEALTHY host step (it is a host change).
+	// A Docker step's outcome does not gate it (the Docker set lives in the guest). Pinned by TestPVE_*.
+	switch {
+	case blk.Ring != 0 || !blk.Enabled:
+		lg.Info("osupdate: pve step skipped — ring 1 takes a Proxmox set only inside a signed operator job (`11` §5.10)", "ring", blk.Ring, "enabled", blk.Enabled)
+	case !l.Appliance || h.Layer == "" || !okStep(h):
+		lg.Info("osupdate: pve step skipped — no healthy host step this pass (an appliance only)", "appliance", l.Appliance, "host_outcome", h.Outcome)
+	default:
+		p.PVE = l.runPVE(ctx, g.RunID, vmid, trigger, blk, dockerOpts{})
 	}
 	return p
 }

+// pveDrainWait bounds how long a pve step waits for the agent's own /etc/pve writes in flight (pvegate).
+var pveDrainWait = 2 * time.Minute
+
+// runPVE runs the pve layer while holding pvegate: the agent's own /etc/pve writes wait until it ends.
+func (l *Leg) runPVE(ctx context.Context, runID string, vmid int, trigger string, blk hub.WireOSUpdate, do dockerOpts) Report {
+	lg := l.log().With("run", runID, "layer", LayerPVE, "vmid", vmid, "trigger", trigger)
+	dctx, cancel := context.WithTimeout(ctx, pveDrainWait)
+	end, err := pvegate.Step(dctx)
+	cancel()
+	if err != nil {
+		return l.finish(ctx, lg, Report{RunID: runID, Layer: LayerPVE, Trigger: trigger, Ring: blk.Ring, VMID: vmid, Mode: "apply",
+			ReleaseID: do.releaseID, Outcome: "failed", HealthReason: "an agent write to /etc/pve did not finish in time (pvegate): " + err.Error()})
+	}
+	lg.Info("osupdate: pve step holds the /etc/pve write gate — the agent's own writes wait until it ends")
+	defer func() {
+		end()
+		lg.Info("osupdate: pve step released the /etc/pve write gate")
+	}()
+	return l.runLayer(ctx, runID, LayerPVE, vmid, trigger, blk, do)
+}
+
 // dockerOpts is a signed Docker step (DockerStepExecutor); the zero value is ring 0's unsigned "pending-docker".
 type dockerOpts struct {
 	releaseID string
@@ -571,7 +651,7 @@ func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigg
 		wire = blk.HostRelease
 	}
 	lane := "fast"
-	if layer == LayerDocker {
+	if layer == LayerDocker || layer == LayerPVE {
 		lane = "slow"
 		if do.signed != nil {
 			rel = hub.WireOSRelease{ID: do.releaseID}
@@ -604,6 +684,13 @@ func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigg
 		}
 	case layer == LayerDocker:
 		plan["select"] = "pending-docker" // ring 0: the wrapper checks the box's ROOT-OWNED ring-0 mark itself
+	case layer == LayerPVE && do.signed != nil:
+		plan["packages"], plan["signed"] = do.packages, do.signed
+		for _, p := range do.packages {
+			planned[p.Name] = true
+		}
+	case layer == LayerPVE:
+		plan["select"] = "pending-pve" // ring 0: the same root-owned mark; the wrapper picks installed Proxmox userspace
 	case !blk.Enabled:
 		plan["mode"] = "inventory"
 		lg.Info("osupdate: switched OFF for this box — reporting only")
@@ -637,6 +724,7 @@ func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigg
 	rep.Upgraded, rep.PassSeconds = wr.Upgraded, wr.PassSeconds
 	rep.DockerEngine, rep.Authority, rep.Undo = wr.DockerEngine, wr.Authority, wr.Undo
 	rep.OOMCheck = rawOrNil(wr.OOMCheck)
+	rep.PVEManager = wr.PVEManager
 	if rep.Outcome == "" {
 		switch {
 		case rep.Mode == "inventory" && !blk.Enabled:
@@ -654,21 +742,27 @@ func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigg
 	}
 	// Health: compare with the start of the pass; give restarted services time (only after an install).
 	cur := wr.HealthAfter
-	wantEngine := ""
+	wantEngine, wantPVE := "", ""
 	for _, u := range wr.Upgraded {
 		if u.Name == "docker-ce" {
 			wantEngine = EngineOf(u.Version)
 		}
+		if u.Name == "pve-manager" {
+			wantPVE = u.Version
+		}
 	}
 	verdict := func(h *Health) (bool, string) {
 		if layer == LayerDocker {
 			return DockerHealthVerdict(wr.HealthBefore, h, wantEngine, wr.DockerEngine)
 		}
-		if layer == LayerHost {
+		if layer == LayerHost || layer == LayerPVE {
 			t := hub.TunnelUnknown
 			if l.Tunnel != nil {
 				t, _ = l.Tunnel.Status(ctx)
 			}
+			if layer == LayerPVE {
+				return PVEHealthVerdict(wr.HealthBefore, h, t, wantPVE, wr.PVEManager)
+			}
 			return HostHealthVerdict(wr.HealthBefore, h, t)
 		}
 		return HealthVerdict(wr.HealthBefore, h)
@@ -708,6 +802,10 @@ func (l *Leg) runLayer(ctx context.Context, runID, layer string, vmid int, trigg
 		// the docker report carries the engine set only (the guest report already carries the Debian packages)
 		rep.Installed, rep.Pending = onlyDocker(wr.Installed), onlyDockerPending(wr.Pending)
 		rep.NotCovered = nil
+	} else if layer == LayerPVE {
+		// the pve report carries the Proxmox userspace set only — the hub's candidate is built from it
+		rep.Installed, rep.Pending = onlyPVE(wr.Installed), onlyPVEPending(wr.Pending)
+		rep.NotCovered = nil
 	} else {
 		rep.NotCovered = notCovered(wr.Pending, blk.Ring, planned)
 	}
@@ -732,6 +830,33 @@ func onlyDocker(in []Package) []Package {
 	return out
 }

+// onlyPVE keeps the installed Proxmox-origin packages the pve lane may touch (never a kernel / boot / firmware name).
+func onlyPVE(in []Package) []Package {
+	var out []Package
+	for _, p := range in {
+		if (p.Origin == InstalledPVEOrigin || p.Origin == PVEOrigin) && !hostSlowRE.MatchString(p.Name) && !DockerNames[p.Name] {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+func onlyPVEPending(in []Pending) []Pending {
+	var out []Pending
+	for _, p := range in {
+		if p.From == "" || hostSlowRE.MatchString(p.Name) || DockerNames[p.Name] {
+			continue
+		}
+		for _, o := range p.Origin {
+			if o == PVEOrigin {
+				out = append(out, p)
+				break
+			}
+		}
+	}
+	return out
+}
+
 func onlyDockerPending(in []Pending) []Pending {
 	var out []Pending
 	for _, p := range in {