Kubernetes Runtime Classes

RuntimeClass lets you select the container runtime for individual pods. Different workloads have different security and performance requirements — high-security workloads can use kernel-isolated runtimes like gVisor or kata-containers while standard workloads continue using containerd with runc. RuntimeClass makes this selection explicit in the pod spec rather than requiring node selector hacks.

Overview

RuntimeClass is the Kubernetes primitive that exposes the security/performance knob for container isolation. It lets each workload make a different isolation choice without changing the deployment interface.

> [!NOTE] Most clusters run everything with runc because it is fast and well understood, but one-size-fits-all is increasingly inadequate for sensitive workloads.

The isolation problem it solves

Linux container namespaces isolate processes from each other, but they share the host kernel. A kernel exploit, or a container runtime escape such as the runc vulnerability CVE-2019-5736, can let a container gain root on the host.

runc — Namespaces on the shared host kernel — Exploit reaches the host
gVisor — User-space kernel between the container and the host — Much harder to leverage
kata-containers — VM boundary — Much harder to leverage

containerd configuration pitfalls

The containerd 2.x series (the current major version as of 2025) changed the default configuration, including the format of config.toml.

containerd version on new clusters — Configuration examples from containerd 1.x may not work verbatim
SystemdCgroup = true in /etc/containerd/config.toml — Essential on any cluster using cgroup v2

> [!WARNING] Without SystemdCgroup = true on cgroup v2, the kubelet and containerd disagree about which cgroup hierarchy to use, and pods fail in hard-to-diagnose ways.

Key concepts

containerd Shim Architecture: containerd does not call runc or gVisor directly. Instead, for each pod sandbox it starts a shim process — a small binary that acts as an adapter between containerd and the low-level runtime. The shim process persists for the lifetime of the sandbox and handles the runtime's lifecycle, I/O forwarding, and exit code reporting. Shim binaries follow a naming convention: containerd-shim--. For runc this is containerd-shim-runc-v2. For gVisor this is containerd-shim-runsc-v1. For kata this is containerd-shim-kata-v2. The shim architecture means that if containerd itself is upgraded or restarted, running pods are not affected — the shim processes continue managing their sandboxes independently. The handler name in the RuntimeClass spec must exactly match the key in the containerd config.toml runtimes section.

When to use it

When running multi-tenant workloads where different tenants' pods should not be able to affect each other even via kernel exploits
When deploying sensitive data processing workloads (PII, financial data, health data) that require stronger isolation guarantees than Linux namespaces
When adding gVisor or kata-containers to an existing cluster and troubleshooting why pods with a runtimeClassName fail to start
When evaluating the performance cost of different isolation levels for a latency-sensitive application

Kubernetes Runtime Classes

Overview

Overview

The isolation problem it solves

containerd configuration pitfalls

Key concepts

When to use it

More DevOps topics