Kubernetes Runtime Class Backup and Restore: A Practical Guide

Intro

Runtime Classes in Kubernetes let you select a container runtime for a pod, such as a lightweight sandbox like gVisor, a high-performance runtime like Kata Containers, or a custom runtime with specific features. Backing up and restoring Runtime Class resources is critical for disaster recovery and cluster migration. If a Runtime Class is missing or misconfigured, pods that reference it will fail to schedule, causing outages. This guide covers practical backup and restore procedures with concrete commands, validation steps, and recovery strategies.

You will learn how to:

• Inventory existing Runtime Classes and their configurations.
• Back up Runtime Class objects using standard Kubernetes tools.
• Restore Runtime Classes in a new or recovered cluster.
• Validate that restored Runtime Classes function correctly.
• Handle common failure modes and roll back safely.

This guide targets developers, DevOps engineers, and platform operators who manage Kubernetes clusters and need to ensure runtime configurations survive disasters.

Version and Environment Inventory

Before backing up Runtime Classes, understand your cluster environment. This section shows how to check the Kubernetes version, confirm the API availability, and list current Runtime Classes.

Prerequisites

• A running Kubernetes cluster with kubectl configured.
• Access to view Runtime Classes (usually cluster-admin or similar).

Check Kubernetes Version

RuntimeClass is available in stable v1 since Kubernetes 1.20. Earlier versions used the node.k8s.io/v1beta1 API. Run:

kubectl version --short

Expected output (example):

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.27.3

If the server version is below 1.20, adjust API versions accordingly. For this guide, we assume v1.

List Existing Runtime Classes

To see all Runtime Classes:

kubectl get runtimeclass

Example output:

NAME        HANDLER     AGE
runc        runc        10d
gvisor      runsc       10d
kata        kata        10d

The HANDLER column shows the runtime handler name configured in the container runtime. It must match the handler in the node's runtime configuration.

Inspect a Specific Runtime Class

View the full definition of a Runtime Class:

kubectl get runtimeclass gvisor -o yaml

Example output:

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
  annotations:
    example.com/description: "Sandboxed runtime for untrusted workloads"
handler: runsc
scheduling:
  nodeSelector:
    runtime: gvisor
  tolerations:
  - key: "sandboxed"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"
overhead:
  podFixed:
    cpu: "100m"
    memory: "128Mi"

This Runtime Class specifies a handler, node selector, tolerations, and pod overhead. All these fields need to be backed up.

Safe Configuration Path

This section covers the safe way to capture Runtime Class configurations for backup. We use read-only operations first to avoid accidental changes.

Extract All Runtime Classes to YAML

To back up all Runtime Classes in a namespace-scoped manner (Runtime Classes are cluster-scoped, so no namespace):

kubectl get runtimeclass -o yaml > runtimeclasses-backup.yaml

This command captures the full definitions. However, the output includes status and metadata like resourceVersion that are not needed and may cause issues on restore. To get a cleaner backup, use --export (deprecated in newer versions) or process the YAML. In Kubernetes 1.18+, --export is deprecated. Instead, use a tool like kubectl neat or manually remove unwanted fields. For simplicity, we will keep the full output and note that kubectl apply ignores some fields automatically, but resourceVersion should be removed before applying to avoid conflict errors.

To programmatically strip undesired fields, use kubectl get -o json and pipe to jq to remove metadata.resourceVersion, metadata.uid, metadata.creationTimestamp, and status:

kubectl get runtimeclass -o json | jq 'del(.items[].metadata.resourceVersion, .items[].metadata.uid, .items[].metadata.creationTimestamp, .items[].metadata.generation, .items[].status)' > runtimeclasses-clean.json

This JSON can be stored as backup.

Also Back Up Custom Resource Definitions (if any)

If your Runtime Classes reference custom handlers that are defined by extensions, ensure those extensions' configuration is also backed up. For example, if you use a custom runtime installed via a DaemonSet, back up that DaemonSet and related ConfigMaps. Explore using kubectl get daemonset -A -o yaml for runtimes like gVisor that are deployed as DaemonSets.

Verify Backup File

Check the backup file exists and has content:

wc -l runtimeclasses-clean.json

Open it to confirm no empty structures.

Verification and Diagnostics

After backing up, verify that the backup is complete and correct. Test restoration in a non-production cluster to ensure the process works.

Create a Test Pod Using the Runtime Class

Before disaster strikes, test that the Runtime Class works. Create a pod that uses gvisor:

# test-gvisor-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: test-gvisor
spec:
  runtimeClassName: gvisor
  containers:
  - name: test
    image: busybox
    command: ["sleep", "3600"]

Apply and check status:

kubectl apply -f test-gvisor-pod.yaml
kubectl get pod test-gvisor

Expected: status Running. If it fails with FailedCreatePodSandBox or CreatePodSandbox for pod failed, the runtime handler is not available on the node.

Verify Node Readiness for Runtime

Check nodes have the runtime configured:

kubectl get nodes -l runtime=gvisor

If no nodes are returned, the nodeSelector in the Runtime Class does not match any nodes, and pods will not schedule.

Test Scheduling and Overhead

Create a pod with resource requests to verify overhead is applied:

kubectl apply -f test-gvisor-pod.yaml
kubectl describe pod test-gvisor | grep -A5 "Requests"

Expected output shows overhead added to container requests.

Failure Modes and Recovery

This section outlines common failure scenarios and how to recover from them.

Runtime Class Missing During Restore

If you attempt to restore a pod that references a Runtime Class that doesn't exist, the pod will fail to schedule. To recover:

1. Check events:

   kubectl describe pod mypod | grep -A10 Events

Look for FailedScheduling with message "runtimeclass.node.k8s.io/gvisor not found".

1. Restore the Runtime Class from backup:

   kubectl apply -f runtimeclasses-backup.yaml

1. Recreate the pod if needed.

Broken Handler Configuration

If the handler in the Runtime Class does not match any configured runtime on the node, pods will fail to create sandbox. Fix by correcting the handler in the Runtime Class or adding the runtime configuration on nodes. For example, if you mistakenly set handler to runc but nodes only have runsc for that class, update the Runtime Class:

kubectl patch runtimeclass gvisor --type='merge' -p '{"handler":"runsc"}'

Then verify pod creation.

Rollback of Runtime Class Changes

If you change a Runtime Class and it causes issues, revert to a previous version. Keep versioned backups. To restore a specific version:

kubectl apply -f backups/runtimeclass-gvisor-20250301.yaml

Use a naming convention with timestamps.

Cluster-wide Disaster Recovery

In a complete cluster loss, restore Runtime Classes as part of your cluster bootstrap. After cluster creation, apply backups before restoring workloads:

kubectl apply -f runtimeclasses-clean.json

Then restore other resources. Ensure order: Runtime Classes before pods/deployments.

Operations Checklist

Use this checklist to ensure you have a complete backup and restore process:

• [ ] Kubernetes version recorded (kubectl version).
• [ ] All Runtime Classes listed and exported to a version-controlled file.
• [ ] Backup file cleaned of resourceVersion and status fields.
• [ ] Backup stored in off-cluster location (e.g., git, object storage).
• [ ] Test restore process in a staging cluster.
• [ ] Test pod scheduling with each Runtime Class.
• [ ] Verify node labels and tolerations match.
• [ ] Document the mapping of handlers to actual runtimes on nodes.
• [ ] Have a rollback plan for Runtime Class changes.
• [ ] Include Runtime Class backup in regular cluster backup jobs.

Example backup script for cron job:

#!/bin/bash
kubectl get runtimeclass -o json | jq 'del(.items[].metadata.resourceVersion, .items[].metadata.uid, .items[].metadata.creationTimestamp, .items[].metadata.generation, .items[].status)' > /backups/runtimeclasses-$(date +%Y%m%d%H%M).json

Conclusion

Backing up and restoring Kubernetes Runtime Classes is a straightforward but critical task. By following the steps in this guide, you can ensure that your runtime configurations survive disasters and that pods referencing specialized runtimes continue to work. The key points are: inventory your Runtime Classes, back them up cleanly, test restoration thoroughly, and be prepared for common failure modes. Regular backups and validation should be part of your operational routine. Start by implementing the basic backup command and then expand to automated scheduled backups with off-cluster storage.