Mastering Kubernetes RuntimeClass: Multi‑Runtime Support and Pod Overhead Explained

Evolution of Container Runtimes

The container runtime landscape has progressed through three major stages. In June 2014, Kubernetes was open‑sourced with Docker as the sole default runtime. With Kubernetes v1.3, the rkt runtime was merged into the core, becoming a second option. By v1.15, many additional runtimes emerged, prompting the community to create the Container Runtime Interface (CRI) to decouple Kubernetes from any specific runtime.

Why RuntimeClass Was Introduced

RuntimeClass was added to address the challenges of supporting multiple container runtimes in a single cluster without bloating the core code. It leverages CRI to allow the scheduler and admission controllers to select the appropriate runtime for each Pod.

RuntimeClass Workflow

RuntimeClass first appeared as a CustomResourceDefinition (CRD) in Kubernetes v1.12, became a built‑in resource in v1.14, and gained scheduling and overhead capabilities in v1.16. A typical workflow (v1.16) involves a YAML manifest that defines a RuntimeClass object (e.g., named runv) and a Pod that references it via spec.runtimeClassName. The RuntimeClass object contains three key fields:

handler : the program that receives container‑creation requests and maps to a specific runtime.

overhead : resources consumed by the runtime beyond the application’s own requests.

scheduling : node‑selector information that influences where the Pod is placed.

RuntimeClass Structure

The RuntimeClass API object includes: handler: identifies the runtime implementation (e.g., runv). overhead (v1.16+): a PodFixed map of ResourceName to Quantity, representing additional CPU, memory, etc., consumed by the runtime. scheduling (v1.16+): contains nodeSelector and tolerations that are merged into the Pod’s own selectors and tolerations during admission.

Pod Overhead Usage and Limitations

Pod Overhead is useful for three scenarios:

Scheduling : Pods are only scheduled to nodes whose available resources exceed requests + overhead.

ResourceQuota : Overhead is counted toward namespace‑level quotas, reducing the number of Pods that can be admitted.

Kubelet eviction : Overhead contributes to node‑resource usage, influencing eviction decisions.

Key constraints:

Overhead is injected automatically by the RuntimeClass admission controller and cannot be manually altered.

Only the admission controller can add Overhead; manual edits are rejected.

Horizontal and Vertical Pod Autoscalers operate on container‑level metrics and ignore Overhead.

Multi‑Runtime Example

Alibaba Cloud ACK’s sandbox supports multiple runtimes. In the example, two Pods are created: one using the runc RuntimeClass and another using runv. Requests are labeled to indicate which runtime they belong to. The request flow is:

Pod request reaches kube-apiserver.

It is forwarded to kubelet, then to the cri-plugin.

The plugin consults containerd configuration to map the handler to the appropriate runtime (e.g., containerd-shim for runc, containerd-shim-kata-v2 for runv).

containerd Configuration

The default containerd config resides at file:///etc/containerd/config.toml. Under plugins.cri.containerd.runtimes, each runtime (e.g., runc, runv) is defined with a matching handler. A special default_runtime entry determines which runtime is used when a Pod does not specify a RuntimeClass.

Creating and Using RuntimeClass Objects

Example YAML files create RuntimeClass objects for runc and runv. After applying them, kubectl get runtimeclass lists the available runtimes. Pods referencing these classes set runtimeClassName accordingly. Once created, kubectl shows both Pods in the Running state, each using its designated runtime.

Key Takeaways

RuntimeClass is a built‑in Kubernetes resource that solves the problem of mixing multiple container runtimes in a single cluster.

Its scheduling field lets Pods automatically land on nodes that support the specified runtime, provided the nodes are labeled appropriately.

The overhead field accounts for runtime‑specific resource consumption, improving scheduling accuracy, ResourceQuota enforcement, and Kubelet eviction behavior.