sandbox

Overview ¶

runtime.go — the Kubernetes half: what a sandbox IS in the cluster, and the one channel into it.

A sandbox is a Pod, and its isolation boundary is the RUNTIME that pod names — one field, `SANDBOX_RUNTIME_CLASS`, holding `gvisor` or `kata-fc` or `kata-clh` or nothing. It is the ONLY boundary claimed here: no uid juggling, no process groups, no daemon inside the pod deciding what it is allowed to run. Everything the predecessor built to approximate that boundary in Go is deleted rather than kept "for defence in depth", because a second half-boundary is a second thing to keep true.

Empty is honest, not a hole: it means the node's default runtime, which is the containment a normal pod gets. It ships that way because runsc has to be installed on the nodes first and that restarts containerd under 204 running pods — maintenance, not a release step. The field flips afterwards with no rebuild, and that is the whole reason the runtime is a string.

There is no os/exec in this file and there must never be. It creates Kubernetes objects and streams bytes to the apiserver.

Package sandbox is the ONE compute primitive: a sandbox is a gVisor pod that runs somebody else's code, and every lifetime is the same object.

a function invoke      = a sandbox with a seconds-long lease
a code-exec call       = a sandbox with a session lease
an agentic coding run  = a sandbox with a project volume and a long lease

Not three subsystems, not three schedulers. One record, one pod spec, one way in. What differs between them is `ttlSec` and whether a volume is attached.

POST   /v1/sandboxes             {kind:"sandbox", class, project?, ttlSec?} -> Sandbox
GET    /v1/sandboxes             ?kind=&project=&status=
GET    /v1/sandboxes/:id
DELETE /v1/sandboxes/:id         ?purge=1 drops the volume too
POST   /v1/sandboxes/:id/exec    {argv|command, stdin?, timeoutSec?} -> {exitCode,stdout,stderr}
GET    /v1/sandboxes/:id/fs      ?path=  read a file, or list a directory
POST   /v1/sandboxes/:id/fs      ?path=  write a file

THERE IS EXACTLY ONE WAY INTO A SANDBOX, and it is the Kubernetes exec subresource. fs read/list/write are not a second channel — they are `cat`, `ls` and `tee` over that one channel, which is also how `kubectl cp` has always worked. The predecessor shipped an in-pod HTTP daemon with eleven endpoints, a shared pool-wide API key and a pod-IP address book; all three are gone, because Kubernetes already had the channel and we were re-implementing it badly.

A SANDBOX IS ADDRESSED BY POD NAME THROUGH THE APISERVER, NEVER BY IP. That is not a style preference, it is the fix for a real cross-tenant read: a pod that dies on its own — evicted, OOM-killed, drained — never runs a release path, so a row keeps a Host the CNI has since handed to another tenant's replacement pod, and a call to that address is served by a stranger with every credential checking out. A pod NAME is minted per sandbox and never reused, so the same mistake cannot be spelled. The header-stamping protocol that was invented to defend the IP scheme is deleted along with the scheme.

NOTHING RUNS IN THIS PACKAGE. There is no os/exec here and there must never be. It creates Kubernetes objects and streams bytes to the apiserver; the work happens inside the pod, under runsc, on the far side of a runtime boundary.

THERE IS NO POOL. A sandbox is created for a lease and deleted at its end. Claiming from a warm pool is what forced the recycle, the pod-IP address book and the label-patch race arbitration; it also grows, inevitably, into a scheduler beside Kubernetes' own. If a warm pool is ever wanted, it is a Deployment an operator sizes — not a manager in this process.

AUTH is the ordinary one: IAM terminates identity at the edge and this package reads principal.Org. It never mints a credential, and no caller credential reaches a sandbox — the pod carries no service-account token at all.