Runtime Class in Kubernetes

This article explains how to instruct Kubernetes Pods to use a specific container runtime implementation (for example, gVisor or Kata Containers) by creating and referencing a RuntimeClass.

Prerequisites

A Kubernetes cluster with nodes that have the alternative runtime installed (for example, gVisor’s runsc or Kata Containers’ kata).
The node’s container runtime (e.g., containerd) must be configured to expose the runtime handler name that you will reference in the RuntimeClass.

What is a RuntimeClass?

RuntimeClass is a cluster-scoped object that allows you to select the container runtime configuration used to run a Pod.
It lets you target Pods to a specific runtime handler available on nodes (for example runsc for gVisor).

Key RuntimeClass fields

Field	Description	Example
`metadata.name`	The name you reference from Pod specs (arbitrary, cluster-scoped)	`gvisor`
`handler`	The runtime implementation name that must match a runtime configured on the node	`runsc`

Ensure the runtime (for example, gVisor / runsc) is installed and configured on every node that may run Pods referring to this RuntimeClass. The handler value must match the runtime name configured in the node’s container runtime (for example, containerd).

Example manifests Below are two manifests you can apply: one for the RuntimeClass itself, and one for a Pod that requests that RuntimeClass. RuntimeClass manifest (save as e.g. gvisor-runtimeclass.yaml):

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc

Pod manifest that uses the RuntimeClass (save as e.g. gvisor-nginx.yaml):

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    run: nginx
spec:
  runtimeClassName: gvisor
  containers:
  - name: nginx
    image: nginx

Apply the manifests with kubectl

$ kubectl create -f gvisor-runtimeclass.yaml
runtimeclass.node.k8s.io/gvisor created

$ kubectl create -f gvisor-nginx.yaml
pod/nginx created

Verify the RuntimeClass and Pod

List available RuntimeClasses:

kubectl get runtimeclass

Inspect the Pod spec to confirm it references runtimeClassName: gvisor:

kubectl get pod nginx -o yaml

Behavior on the node When a Pod uses a runtime handler such as runsc (gVisor), the container process runs inside the runtime’s sandbox. Because gVisor provides a user-space kernel boundary, the containerized process is isolated from the node kernel and does not appear as a normal host process. Example on the node:

$ node01:~# pgrep -a nginx
$ node01:~# pgrep -a runsc
27259 runsc --root=/run/containerd/runsc/k8s.io --log=/run/containerd/io.containerd.runtime.v2.task/k8s.io/<id>/log.json --log-format=json

This shows the container is sandboxed (the container runtime process such as runsc is visible, while the container’s internal process is not shown to the host kernel). Links and references

Introduction

Understanding the Kubernetes Attack Surface

Cluster Setup and Hardening

System Hardening

Minimize Microservice Vulnerabilities

Supply Chain Security

Monitoring, Logging and Runtime Security

Runtime Class in Kubernetes

Watch Video

Practice Lab