feat(kubernetes): warm-pooled sandboxes via agent-sandbox extension CRDs

[rmalani-nv]

Summary

Implements warm-pooled sandboxes on the Kubernetes compute driver (#1879). Instead of cold-starting a Sandbox CR per request, the gateway claims a pre-warmed pod from an operator-declared warm pool by creating an agent-sandbox SandboxClaim (extensions.agents.x-k8s.io/v1alpha1), cutting provisioning from pod-startup time to near-instant.

This supersedes the closed groundwork PR #1813 (RFC + extension install): it keeps that groundwork at the base of the branch and folds in the full driver/server/supervisor implementation plus the security remediation items raised in the #1813 review.

Warm pooling is off by default (server.warmPool.enabled=false); with it disabled the cold path is unchanged. Validated end-to-end on a local k3s (k3d) cluster.

Security-sensitive change — please review closely

A warm pod's owning Sandbox CR is created generically by the pool controller and carries no OpenShell sandbox-id, so IssueSandboxToken re-anchors identity through a fail-closed chain: pod → owning Sandbox → controlling SandboxClaim → live bound claim → durable gateway-written claim mapping (crates/openshell-server/src/auth/k8s_sa.rs). Any broken link denies the token. Custom-policy requests never warm-pool (Landlock is applied once at boot and cannot be loosened), and the sandbox pod ServiceAccount is granted no claim/template/pool access.

Related Issue

Closes #1879. Addresses the security remediation items from the #1813 review (fail-closed eligibility, identity re-anchor, single-use workspace, least-privilege RBAC).

Changes

Stacked commits, in dependency order:

• feat(compute-driver) — extend the gRPC contract: WarmClaimBinding on CreateSandboxResponse, claim_name/claim_uid on DriverSandboxStatus, disallow_warm_pool on DriverSandboxSpec; adapt the Docker/Podman/VM drivers (they don't warm-pool).
• refactor(core) — centralize agent-sandbox CRD identity (group/version/kind, claim-uid label, sandbox-id annotation) in openshell-core so the driver and the auth path can't drift.
• feat(server) persistence — durable, HA-safe (namespace, claim_name, claim_uid) → sandbox_id mapping; rebinding a key to a different id is rejected.
• feat(kubernetes) — reconcile warm pools (one SandboxTemplate + SandboxWarmPool per pool), bind pre-warmed pods via SandboxClaim, and watch claims to surface warm sandboxes. warm_eligible() exhaustively destructures the request spec/template, so any newly added field must be classified before it can ride the warm path.
• feat(server) re-anchor — the fail-closed identity chain above, plus a synchronous mapping write with claim rollback, crash-window backfill bounded to gateway-minted ids, and orphan GC.
• feat(sandbox) — the supervisor boots identity-less on the image baseline policy; the gateway derives the sandbox id from the gateway-minted JWT when the supervisor hello carries none, with a fast bootstrap retry while the claim binds.
• feat(deploy) — warm-pool gateway.toml rendering, a values-warm-pool.yaml CI overlay, and least-privilege RBAC (SSA create+patch on templates/pools; create/delete/get/list/watch on claims; no status subresources).
• test(e2e) — workspace single-use across re-claims, read-only shared volume, and cold-fallback for custom-policy requests (gated on OPENSHELL_E2E_WARM_POOL).
• docs — config reference, driver README, and RFC 0005 updated to the validated design.

Testing

Validated on a local k3s (k3d) cluster during development:

• Drove a real SandboxTemplate → SandboxWarmPool → SandboxClaim cycle: a claim binds a pre-warmed pod near-instantly, the openshell.io/sandbox-id annotation lands on the pod, and the pool self-replenishes.
• Warm-path sandbox create reaches Ready and runs a command over the supervisor relay; the cold-path baseline is unchanged.
• warm_pool_workspace_isolation (workspace single-use + read-only shared volume) passed live on k3d.

This change set:

• mise run pre-commit ✓ (lint / format / license).

• Targeted unit tests pass: warm_eligible (Kubernetes driver) and the auth::k8s_sa re-anchor suite (30 tests, including spoofed-label, uid-mismatch, and store-mapping-spoof cases).

• Added a cold-fallback e2e assertion (compiles under e2e-kubernetes; runs in the gated warm-pool e2e).

• Ran an adversarial multi-dimension review over the diff; it surfaced one over-trimmed RBAC verb (claims watch, which the driver's claim watcher needs) — now fixed and re-verified against the rendered chart.

• Full unit/integration suite and e2e run in CI.

• mise run pre-commit passes

• Unit tests added/updated — warm_eligible, auth re-anchor (incl. adversarial cases), persistence mappings

• E2E tests added/updated — warm-pool workspace isolation + cold-fallback

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable) — RFC 0005, the Kubernetes driver README, and the gateway config reference document the warm-pool design and configuration

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.