@namzu/sandbox 13.0.0 → 14.0.0

package/src/index.ts

@@ -44,6 +44,17 @@ import type {
 import { buildAciStandbyPoolBackend } from './backends/aci-standby-pool/index.js'
 import { buildDockerBackend, resolveLayout } from './backends/docker/index.js'
 import { buildFirecrackerBackend } from './backends/firecracker/index.js'
+import type { KubernetesEgressConfig } from './backends/kubernetes/egress-policy.js'
+import {
+	type KubernetesBackendInternalConfig,
+	type KubernetesClusterAccess,
+	buildKubernetesBackend,
+} from './backends/kubernetes/index.js'
+import {
+	type KubernetesWorkspace,
+	type KubernetesWorkspaceOptions,
+	createKubernetesWorkspace as buildKubernetesWorkspace,
+} from './backends/kubernetes/workspace.js'
 
 // Re-export the layout types so consumers of `@namzu/sandbox` can
 // import them without also depending on `@namzu/sdk`. The canonical
@@ -78,12 +89,57 @@ export type {
 	OrchestratorTokenProvider,
 } from './backends/firecracker/index.js'
 export {
+	AgentPreauthFrameTooLargeError,
 	FIRECRACKER_AGENT_PROTOCOL_VERSION,
 	type SandboxAgentHandle,
+	TCP_PREAUTH_FRAME_LIMIT_BYTES,
 	type VsockTransportOptions,
 	VsockAgentTransport,
 } from './backends/firecracker/transport.js'
 
+// Kubernetes (agent-sandbox on any cluster) public surface. The access union
+// is named by `KubernetesBackendConfig.access`, so a host that builds its own
+// credential callback can name what it is passing.
+export type { KubernetesClusterAccess } from './backends/kubernetes/index.js'
+// Egress translation types named by `KubernetesBackendConfig.egress` — see
+// `backends/kubernetes/egress-policy.ts` for what each engine can express.
+export type {
+	KubernetesEgressConfig,
+	KubernetesEgressEngine,
+} from './backends/kubernetes/egress-policy.js'
+// The errors a caller of a kubernetes sandbox has to be able to catch BY
+// CLASS rather than by matching a message: an acquire refused because the
+// guest is not deprivileged, a call after the handle ended (this host
+// destroyed it, or the cluster deleted it), and a rejected agent token.
+export {
+	KubernetesPrivilegeProbeError,
+	type PrivilegeProbeFailure,
+	type ProcStatusPrivileges,
+} from './backends/kubernetes/privilege-probe.js'
+export {
+	KubernetesSandboxDestroyedError,
+	KubernetesSandboxGoneError,
+} from './backends/kubernetes/sandbox.js'
+export { KubernetesAgentUnauthorizedError } from './backends/kubernetes/transport.js'
+// The persistent workspace: a `Sandbox` that keeps a block disk across a
+// suspend, plus the four errors its lifecycle can refuse with — a template
+// that cannot carry a disk, a standing object that does not match this
+// configuration, a call on a suspended workspace, and a suspend whose pod
+// outlived the wait. Declared in `@namzu/sandbox` rather than on the SDK's
+// `Sandbox` — see `backends/kubernetes/workspace.ts`.
+export type {
+	KubernetesWorkspace,
+	KubernetesWorkspaceDestroyOptions,
+	KubernetesWorkspaceOptions,
+	KubernetesWorkspaceTransitionOptions,
+} from './backends/kubernetes/workspace.js'
+export {
+	KubernetesWorkspaceDiskError,
+	KubernetesWorkspaceMismatchError,
+	KubernetesWorkspaceSuspendTimeoutError,
+	KubernetesWorkspaceSuspendedError,
+} from './backends/kubernetes/workspace.js'
+
 // ---------------------------------------------------------------------------
 // Backend strategy
 // ---------------------------------------------------------------------------
@@ -120,6 +176,7 @@ export type SandboxBackendConfig =
 	| ContainerBackendConfig
 	| ACIStandbyPoolBackendConfig
 	| MicroVMBackendConfig
+	| KubernetesBackendConfig
 
 /**
  * Azure Container Instances Standby Pool backend. Container tier,
@@ -375,6 +432,101 @@ export interface AgentSnapshotRef {
 	readonly version: string
 }
 
+/**
+ * `microvm` tier, against a Kubernetes cluster running the agent-sandbox
+ * controller (kubernetes-sigs/agent-sandbox) with a VM-isolating
+ * RuntimeClass such as Kata.
+ *
+ * `microvm` because the tier names the strength of the boundary rather than
+ * the orchestrator behind it: a pod scheduled onto a Kata RuntimeClass runs
+ * in a hardware-virtualized guest, and the same field on the same tier is how
+ * a host says "give me a VM, I do not care who starts it".
+ *
+ * Sandboxes are claimed out of a `SandboxWarmPool` when {@link warmPoolName}
+ * names one, which is what makes the acquire sub-second; without it every
+ * create is a `Sandbox` built from {@link sandboxTemplateName}'s podTemplate
+ * and pays a full pod start. This package speaks the API server with bare
+ * `fetch` and carries no Kubernetes client dependency: credentials arrive
+ * through {@link access}, and kubeconfig parsing (context merging,
+ * exec credential plugins) stays in the host that owns it.
+ */
+export interface KubernetesBackendConfig {
+	readonly tier: 'microvm'
+	readonly service: 'kubernetes'
+	/** Namespace the claims, sandboxes and their pods live in. */
+	readonly namespace: string
+	/**
+	 * How to reach the API server. `{ inCluster: true }` reads the projected
+	 * ServiceAccount volume and the kubelet's `KUBERNETES_SERVICE_*` env, which
+	 * is the production path; otherwise the host supplies the server URL, an
+	 * optional cluster CA and a `getToken()` callback — the same boundary this
+	 * package already draws for ACI's `getArmToken` and Firecracker's
+	 * `getToken`.
+	 */
+	readonly access: KubernetesClusterAccess
+	/**
+	 * `SandboxTemplate` whose `podTemplate` a POOL-LESS create copies into the
+	 * `Sandbox` it posts. Required because `Sandbox.spec` has no `templateRef`
+	 * — only a `SandboxWarmPool` references a template — so the pod spec has to
+	 * be carried across by the client. The warm path does not read it; the
+	 * pool's own `sandboxTemplateRef` decides there.
+	 */
+	readonly sandboxTemplateName: string
+	/**
+	 * `SandboxWarmPool` to claim from. Absent → every create posts a `Sandbox`
+	 * directly, because `SandboxClaim.spec.warmPoolRef` is a required field and
+	 * a pool-less claim does not exist in the API.
+	 */
+	readonly warmPoolName?: string
+	/** TCP port the in-pod guest agent listens on. Default 1024. */
+	readonly agentPort?: number
+	/** Delay between readiness polls. Default 50ms. */
+	readonly readyPollIntervalMs?: number
+	/** Total deadline from create to an addressed, Ready sandbox. Default 60000ms. */
+	readonly readyTimeoutMs?: number
+	/**
+	 * Wall-clock lifetime written into every object this backend creates, so a
+	 * host that dies mid-run costs the cluster one expiry rather than a leaked
+	 * sandbox. Default 3600.
+	 */
+	readonly claimTtlSeconds?: number
+	/**
+	 * Every lease-renewal failure that is not "the object is already gone".
+	 *
+	 * The handle renews its own `shutdownTime` every half-TTL for as long as
+	 * it is alive, so a run that outlives `claimTtlSeconds` keeps its pod.
+	 * A failed renewal is retried on the next tick, half a TTL before
+	 * anything expires; this callback is where the diagnostic goes, because
+	 * `@namzu/sandbox` owns no logger and reads none from module scope.
+	 * Setting it changes nothing about behaviour.
+	 */
+	readonly onLeaseRenewalError?: (error: unknown) => void
+	/**
+	 * RuntimeClass for a POOL-LESS create. Refused together with
+	 * {@link warmPoolName}: a pooled sandbox is already running under the
+	 * RuntimeClass its `SandboxTemplate` named, and a claim cannot change it —
+	 * so accepting it there would quietly drop the choice of VM boundary.
+	 */
+	readonly runtimeClassName?: string
+	/**
+	 * Egress policy this backend expects an operator to have applied as a
+	 * `NetworkPolicy` (or, under `engine: 'cilium'`, a `CiliumNetworkPolicy`)
+	 * scoped to every Sandbox this backend produces. Unset means this backend
+	 * neither computes nor checks one — the cluster's default posture (the
+	 * `SandboxTemplate`'s own managed `NetworkPolicy`) is all that applies.
+	 *
+	 * This is a CONFIG-level, whole-backend policy, not a per-`create()` one:
+	 * `SandboxBackendOptions.egress` is still refused by name (see
+	 * `backends/kubernetes/index.ts`'s `assertEnforceable`), because the
+	 * enforcement point is one object attached to the template and cannot be
+	 * rewritten per running sandbox. `static` and `resolver` — hostname
+	 * allowlists — throw a named error at construction unless `engine` is
+	 * `'cilium'`: core `NetworkPolicy` has no FQDN concept at all. See
+	 * `docs/sdk/kubernetes-sandbox.md`'s egress section.
+	 */
+	readonly egress?: KubernetesEgressConfig
+}
+
 /**
  * Egress allowlist resolution. Host-supplied policy decides whether
  * an outbound request is allowed before the proxy opens a socket.
@@ -505,9 +657,16 @@ export type SandboxProviderConfig =
 			readonly backend: ContainerBackendConfig
 			readonly layout: ContainerSandboxLayout
 	  })
+	| (SandboxProviderConfigBase & {
+			readonly backend: ACIStandbyPoolBackendConfig
+			readonly layout: ContainerSandboxLayout
+	  })
 	| (SandboxProviderConfigBase & {
 			readonly backend: MicroVMBackendConfig
 	  })
+	| (SandboxProviderConfigBase & {
+			readonly backend: KubernetesBackendConfig
+	  })
 
 interface SandboxProviderConfigBase {
 	readonly defaultEgress?: EgressPolicy
@@ -580,6 +739,40 @@ export function createSandboxProvider(config: SandboxProviderConfig): SandboxPro
 
 function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 	const backend = config.backend
+	// Checked ahead of the `docker` default below: `ACIStandbyPoolBackendConfig`
+	// is a real arm of `SandboxProviderConfig` (see the discriminated union
+	// above), discriminated from `ContainerBackendConfig` by `runtime`. A
+	// plain equality check here narrows `backend` to the ACI shape with no
+	// cast, and — because this branch always returns — narrows it AWAY for
+	// every check below, so the `docker` branch's `backend.runtime ?? 'docker'`
+	// still sees only `ContainerBackendConfig`.
+	if (backend.tier === 'container' && backend.runtime === 'aci-standby-pool') {
+		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
+			.layout
+		const resolved = resolveLayout(layout)
+		return buildAciStandbyPoolBackend({
+			subscriptionId: backend.subscriptionId,
+			resourceGroup: backend.resourceGroup,
+			location: backend.location,
+			standbyPoolResourceId: backend.standbyPoolResourceId,
+			containerGroupProfileResourceId: backend.containerGroupProfileResourceId,
+			...(backend.containerGroupProfileRevision !== undefined
+				? { containerGroupProfileRevision: backend.containerGroupProfileRevision }
+				: {}),
+			layout: resolved,
+			getArmToken: backend.getArmToken,
+			...(backend.subnetId !== undefined ? { subnetId: backend.subnetId } : {}),
+			...(backend.readyPollIntervalMs !== undefined
+				? { readyPollIntervalMs: backend.readyPollIntervalMs }
+				: {}),
+			...(backend.readyTimeoutMs !== undefined ? { readyTimeoutMs: backend.readyTimeoutMs } : {}),
+			...(backend.workerPort !== undefined ? { workerPort: backend.workerPort } : {}),
+			...(backend.armApiVersion !== undefined ? { armApiVersion: backend.armApiVersion } : {}),
+			...(backend.containerNamePrefix !== undefined
+				? { containerNamePrefix: backend.containerNamePrefix }
+				: {}),
+		})
+	}
 	if (backend.tier === 'container' && (backend.runtime ?? 'docker') === 'docker') {
 		// `layout` is required for container-tier backends by the
 		// discriminated union — narrow safely without a non-null
@@ -605,41 +798,6 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
 		})
 	}
-	if (
-		backend.tier === 'container' &&
-		(backend as unknown as { runtime?: string }).runtime === 'aci-standby-pool'
-	) {
-		const aciBackend = backend as unknown as ACIStandbyPoolBackendConfig
-		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
-			.layout
-		const resolved = resolveLayout(layout)
-		return buildAciStandbyPoolBackend({
-			subscriptionId: aciBackend.subscriptionId,
-			resourceGroup: aciBackend.resourceGroup,
-			location: aciBackend.location,
-			standbyPoolResourceId: aciBackend.standbyPoolResourceId,
-			containerGroupProfileResourceId: aciBackend.containerGroupProfileResourceId,
-			...(aciBackend.containerGroupProfileRevision !== undefined
-				? { containerGroupProfileRevision: aciBackend.containerGroupProfileRevision }
-				: {}),
-			layout: resolved,
-			getArmToken: aciBackend.getArmToken,
-			...(aciBackend.subnetId !== undefined ? { subnetId: aciBackend.subnetId } : {}),
-			...(aciBackend.readyPollIntervalMs !== undefined
-				? { readyPollIntervalMs: aciBackend.readyPollIntervalMs }
-				: {}),
-			...(aciBackend.readyTimeoutMs !== undefined
-				? { readyTimeoutMs: aciBackend.readyTimeoutMs }
-				: {}),
-			...(aciBackend.workerPort !== undefined ? { workerPort: aciBackend.workerPort } : {}),
-			...(aciBackend.armApiVersion !== undefined
-				? { armApiVersion: aciBackend.armApiVersion }
-				: {}),
-			...(aciBackend.containerNamePrefix !== undefined
-				? { containerNamePrefix: aciBackend.containerNamePrefix }
-				: {}),
-		})
-	}
 	if (backend.tier === 'container' && backend.runtime === 'runsc') {
 		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
 			.layout
@@ -688,9 +846,73 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 				: {}),
 		})
 	}
+	// `microvm:kubernetes` — agent-sandbox on any cluster. Reached through a
+	// real arm of `SandboxProviderConfig`, so `backend` narrows here and every
+	// field below is read off the narrowed type, same as the ACI and docker
+	// branches above.
+	if (backend.tier === 'microvm' && backend.service === 'kubernetes') {
+		return buildKubernetesBackend(kubernetesInternalConfig(backend))
+	}
 	throw new SandboxBackendNotImplementedError(describeBackend(backend))
 }
 
+/**
+ * Public config → the kubernetes backend's own. One function so the two
+ * entry points that build against a cluster — {@link createSandboxProvider}
+ * for task sandboxes and {@link createKubernetesWorkspace} for persistent
+ * ones — cannot drift apart on which fields they forward.
+ */
+function kubernetesInternalConfig(
+	backend: KubernetesBackendConfig,
+): KubernetesBackendInternalConfig {
+	return {
+		access: backend.access,
+		namespace: backend.namespace,
+		sandboxTemplateName: backend.sandboxTemplateName,
+		...(backend.warmPoolName !== undefined ? { warmPoolName: backend.warmPoolName } : {}),
+		...(backend.agentPort !== undefined ? { agentPort: backend.agentPort } : {}),
+		...(backend.readyPollIntervalMs !== undefined
+			? { readyPollIntervalMs: backend.readyPollIntervalMs }
+			: {}),
+		...(backend.readyTimeoutMs !== undefined ? { readyTimeoutMs: backend.readyTimeoutMs } : {}),
+		...(backend.claimTtlSeconds !== undefined ? { claimTtlSeconds: backend.claimTtlSeconds } : {}),
+		...(backend.onLeaseRenewalError !== undefined
+			? { onLeaseRenewalError: backend.onLeaseRenewalError }
+			: {}),
+		...(backend.runtimeClassName !== undefined
+			? { runtimeClassName: backend.runtimeClassName }
+			: {}),
+		...(backend.egress !== undefined ? { egress: backend.egress } : {}),
+	}
+}
+
+/**
+ * Create — or reattach to — a persistent workspace on a cluster running the
+ * agent-sandbox controller.
+ *
+ * A workspace is the other half of this backend, and deliberately not
+ * something {@link createSandboxProvider} can hand out: a `SandboxProvider`
+ * promises an EPHEMERAL sandbox per run (`workspaceModes: ['ephemeral']`),
+ * while this returns one object with a name the caller chose, a disk that
+ * survives a suspend, and a lifetime nothing reaps on a timer. It is its own
+ * verb so that the difference is visible at the call site.
+ *
+ * `config.warmPoolName` is ignored here: a workspace is always a `Sandbox`
+ * POSTed directly, because a claim cannot carry the immutable disk spec.
+ * `config.sandboxTemplateName` is the default template, and
+ * `options.sandboxTemplateName` overrides it — a deployment normally has a
+ * task template with no disk and a workspace template with a block one.
+ *
+ * Resolves once the workspace is Ready, addressed and has proved it is
+ * deprivileged, exactly as `provider.create()` does for a task sandbox.
+ */
+export async function createKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	options: KubernetesWorkspaceOptions,
+): Promise<KubernetesWorkspace> {
+	return await buildKubernetesWorkspace(kubernetesInternalConfig(config), options)
+}
+
 /**
  * Human-readable backend label for error messages. Returns the
  * tier plus the concrete service / runtime when present, e.g.