Wiki · Concept · Last reviewed June 25, 2026

Kubernetes RuntimeClass

Kubernetes RuntimeClass lets a pod request a named container runtime configuration, such as a more isolated runtime for untrusted agent work.

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

Definition

Kubernetes RuntimeClass is a cluster-scoped API object in the node.k8s.io/v1 API group. It names a container runtime configuration that a pod can request through spec.runtimeClassName. Kubernetes documentation describes RuntimeClass as the runtime selection mechanism used to run a pod's containers, and lists it as stable since Kubernetes v1.20.

The object is small but consequential. Its name is the handle a workload author puts into a pod spec. Its handler names the corresponding Container Runtime Interface configuration on the node. The kubelet uses that handler when it asks the runtime to start the pod. If no runtimeClassName is set, Kubernetes uses the default runtime handler.

How It Works

RuntimeClass begins outside the API object. A cluster operator configures one or more CRI runtime handlers on the nodes. For each handler that should be selectable by workloads, the operator creates a RuntimeClass object. Kubernetes documentation says the RuntimeClass name must be a valid DNS subdomain name and the handler must be a valid DNS label name.

When a pod names a RuntimeClass, the kubelet attempts to use the corresponding handler. If the named RuntimeClass does not exist, or the CRI implementation cannot run the handler, the pod enters the Failed terminal phase and emits an event with the error. That means RuntimeClass is not a decorative tag. It is part of the pod execution path.

The object can also carry a scheduling field. In a heterogeneous cluster, where only some nodes support a runtime, RuntimeClass can define a node selector and tolerations. The node selector is merged with the pod's own selector at admission; if the selectors conflict, the pod is rejected. Tolerations from the RuntimeClass are merged with pod tolerations so workloads can land on nodes tainted for that runtime.

RuntimeClass can also define pod overhead. Kubernetes documentation describes Pod Overhead as accounting for resources consumed by the pod infrastructure in addition to the container requests and limits. That overhead is set at admission time from the RuntimeClass and is considered by scheduling, pod cgroup sizing, and eviction ranking.

Agent Context

For AI infrastructure, RuntimeClass is a boundary selector. Model-serving pods, trusted internal workers, untrusted code runners, browser automation agents, scraping jobs, and tool servers do not always deserve the same runtime assumptions. A coding agent that runs third-party repository tests may need a different isolation profile than a telemetry exporter or a batch embedding job.

Kubernetes documentation gives the general tradeoff: a workload that needs stronger information-security assurance might use a runtime with hardware virtualization, accepting extra overhead for additional isolation. In agent systems, that tradeoff should be explicit. RuntimeClass can make the requested runtime visible in the pod spec, auditable in admission records, and enforceable by policy.

Governance Use

A governance-grade RuntimeClass record should preserve the class name, handler, CRI implementation, supported node pool, node labels, taints and tolerations, overhead values, owning platform team, allowed namespaces, admission policies that require or block it, and the threat model it is meant to address.

For AI workloads, the record should name the workload category: model serving, evaluation, data processing, browsing agent, code execution agent, tool server, or research sandbox. It should also state what the runtime does not promise. A runtime class can select a container runtime configuration; it does not decide whether the model output is safe, the prompt is authorized, the tool call is appropriate, or the dataset is lawful.

Limits

RuntimeClass is only as useful as the runtime configuration behind it. If the handler is missing, misconfigured, or available only on the wrong nodes, the pod will not receive the intended boundary. If admission policy allows tenants to omit or spoof expectations, the visible runtime plan can drift away from the actual risk model.

It should therefore sit beside ValidatingAdmissionPolicy, NetworkPolicy, Pod Security Standards, ResourceQuota, workload identity, image provenance, logging, and human approval for high-risk tool access.

Source Discipline

Claims about RuntimeClass behavior should cite the Kubernetes Runtime Class concept page, the RuntimeClass API reference, Pod Overhead documentation, Advanced Pod Configuration, and the container-runtime setup documentation. Claims about sandboxing value should be framed as deployment analysis unless supported by the runtime vendor's own security model and independent evaluation.

Do not turn runtimeClassName into a security halo. It is a routing instruction to the cluster runtime layer. The real assurance depends on node configuration, runtime implementation, admission policy, observability, and what the workload is allowed to reach after it starts.

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