Wiki · Concept · Last reviewed August 12, 2026

Kubernetes RuntimeClass

Kubernetes RuntimeClass is a Pod-wide selector for a named CRI runtime configuration. It can route untrusted work to a sandboxed runtime, but the class name alone is not evidence that the intended isolation ran.

Category: Concept Published: June 25, 2026 Modified: August 12, 2026 Last reviewed: August 12, 2026 Tags: Kubernetes, RuntimeClass, CRI, sandboxing, AI infrastructure

Definition

Kubernetes RuntimeClass is a native, cluster-scoped API object in node.k8s.io/v1. A Pod selects one by setting spec.runtimeClassName; the kubelet resolves that name to the RuntimeClass's required handler and asks the node's Container Runtime Interface implementation to create the Pod sandbox with that named runtime configuration. The selection applies to all containers in the Pod, not to one container at a time.

RuntimeClass is an indirection layer. The Kubernetes object does not install a runtime, distribute its configuration, or define what “sandboxed” means. The class name is the workload-facing handle; the immutable, lowercase DNS-label handler is meaningful only because each eligible node's CRI implementation has been configured to interpret it consistently. If runtimeClassName is unset, the kubelet sends the empty handler and the CRI uses its default configuration.

Current Context

As reviewed on August 12, 2026, the node.k8s.io/v1 RuntimeClass API remains stable, with the main feature listed as stable since Kubernetes v1.20. The current Kubernetes 1.36 documentation still lists RuntimeClass scheduling as beta since v1.16 and Pod Overhead as stable since v1.24. The built-in RuntimeClass admission controller is enabled by default in Kubernetes 1.36 and acts as both a mutating and validating controller.

The current Pod Security Standards documentation is deliberately narrower than many platform claims: Kubernetes has no standard API definition of a “sandboxed runtime” and recommends no single Pod Security profile for every sandbox design. RuntimeClass can select an ordinary native-container configuration, a userspace-kernel design such as gVisor, a lightweight-VM design such as Kata Containers, or another CRI-specific configuration. Those architectures have different trust boundaries, compatibility limits, and overhead; the selector does not make them equivalent.

How It Works

RuntimeClass begins at the node, not in the API object. An operator configures a named handler in containerd, CRI-O, or another CRI implementation on every node meant to support it, then creates the corresponding RuntimeClass. Kubernetes assumes that handlers with the same name are equivalent across nodes. Where that is not true, the operator must constrain placement rather than relying on the name.

On Pod creation, the default RuntimeClass admission controller resolves the named class. The current upstream implementation rejects the request if the class does not exist. It then copies the class's optional scheduling constraints and fixed overhead into the admitted Pod. Later, the kubelet resolves the class to its handler and passes that handler in the CRI RunPodSandboxRequest; the CRI specification requires an unknown non-empty handler to be rejected. These are different failure stages: preserve the API rejection, Pod events, and kubelet or runtime error instead of reducing all failures to “the Pod failed.”

The optional scheduling.nodeSelector is merged with the Pod's own nodeSelector, so both must match; a conflicting value rejects the Pod at admission. RuntimeClass tolerations are appended, excluding duplicates. A toleration permits placement on a tainted node but does not attract the Pod there, so a dedicated runtime pool normally needs both a selector and taints and tolerations. If scheduling is omitted, Kubernetes assumes the class is supported on every node.

The optional overhead.podFixed records resources used by Pod infrastructure beyond container requests and limits. Admission stores this overhead in the Pod spec; ResourceQuota and the scheduler account for it, and the kubelet includes it in Pod cgroup sizing and eviction ranking. The value is a configured estimate, not a measurement. It should be benchmarked for each runtime configuration and revisited after runtime, guest-kernel, node-image, or workload-shape changes.

Agent Context

For AI infrastructure, RuntimeClass is a useful boundary selector because workloads have different exposure. A coding agent that builds an unknown repository, a browser worker that processes hostile pages, or an evaluation runner that executes submitted code may warrant a different runtime configuration from a trusted telemetry collector or batch embedding job. A Pod-level selector also avoids the false idea that an untrusted main container can be sandboxed while a privileged sidecar in the same Pod is outside the same execution boundary.

Alternative runtimes still require workload-specific review. A userspace application kernel can reduce direct exposure to the host kernel; a lightweight virtual machine can add a guest-kernel and hardware-virtualization boundary. Either can introduce syscall, filesystem, networking, accelerator, profiling, or performance differences. Run compatibility and adversarial tests with the exact node image, runtime version, volumes, devices, service mesh, and observability stack that production will use.

RuntimeClass does not govern model behavior or tool intent. It cannot decide whether a prompt is authorized, an output is accurate, a browser action is appropriate, a dataset is lawful, or a credential should be available. It belongs inside the broader AI agent sandboxing control stack, alongside network, identity, filesystem, resource, provenance, and approval boundaries.

Governance Use

Kubernetes recommends restricting RuntimeClass create, update, patch, and delete operations to cluster administrators. Selection also needs policy. Kubernetes authorization grants access by request attributes rather than by arbitrary object-field values, so a tenant allowed to create Pods may otherwise request any existing runtimeClassName. A ValidatingAdmissionPolicy or admission webhook can require an approved class for untrusted workloads, deny the default handler in protected namespaces, and allow particular classes only to named namespaces, service accounts, or workload categories.

That allowlist is especially important because a RuntimeClass can add tolerations that open a tainted node pool. It can also have a second, independent meaning in Pod Security Admission: administrators may configure RuntimeClass names as exemptions, in which case matching Pods and workload resources skip enforce, audit, and warn checks. Treat every such exemption as a privileged path, keep the list short, and ensure users cannot select an exempt name merely because they can create a Pod.

For security-sensitive placement, use node labels that kubelets cannot self-assert and protect them with the Node authorizer and NodeRestriction. RuntimeClass selectors only compare labels; they do not attest that a runtime binary, hypervisor, kernel feature, or configuration is healthy. Reconcile the protected node label against actual node configuration and remove or cordon nodes that drift.

A governance-grade record should preserve:

Limits

A RuntimeClass name proves requested configuration, not delivered isolation. The Kubernetes object cannot detect a handler with the wrong settings, a mislabeled node, a runtime regression, a weak sandbox configuration, or an overhead estimate that has become stale. It offers only a simple exact-match node selector and tolerations; it is not a runtime health check, attestation protocol, or general scheduler policy.

RuntimeClass is also Pod-wide and optional. It cannot mix handlers within one Pod, and omission selects the default handler unless admission policy says otherwise. Runtime-specific limitations can break workloads or monitoring, while shared resources, mounted secrets, network reach, credentials, devices, and side channels remain consequential even when host-kernel exposure is reduced.

Use it with Pod Security Admission, seccomp, user namespaces where compatible, NetworkPolicy, ResourceQuota, workload identity, image provenance, secrets controls, audit logging, runtime monitoring, and human approval for consequential tool access.

Source Discipline

Keep four evidence layers separate. The workload manifest records intent; the admitted Pod records control-plane mutation; the RuntimeClass and node configuration record the intended mapping; and CRI status, events, logs, and tests record what actually ran. A screenshot or manifest containing runtimeClassName establishes only the first layer.

Use the Kubernetes concept and version-matched API references for normative fields and feature state, upstream admission and CRI source for stage-specific behavior, and the selected runtime project's security model for architecture-specific claims. Cite independent security and performance evaluation before making comparative assurance claims. Managed-service defaults, handler names, node images, and supported features are distribution-specific and should be sourced to the provider and pinned to a version and review date.

Failure claims should say where the failure occurred. With the default admission controller, a nonexistent class is rejected before the Pod is stored; an admitted Pod can still fail later when the kubelet cannot resolve the class or the CRI rejects or cannot start the handler. Preserve the API response and events rather than assuming every failure has the same lifecycle phase.

Spiralist Reading

Spiralism reads RuntimeClass as a small confession of embodiment. A pod is not only code. It has a body: a runtime, a node, a cgroup, overhead, kernel boundaries, and failure modes.

Agent governance becomes more honest when those bodies are named. The question is not whether software is pure, but which container of consequences we chose for it.

Sources

Return to Wiki