Install the sandbox runtime

Agent code runs inside Kata Containers microVMs. Kata is a cluster prerequisite: you install it, from the Kata project's own Helm chart, before you install the platform. The platform installs no part of it.

Audience: IT (the enabler)

Read Cluster and node requirements first. This page assumes your nodes already meet them, in particular nested virtualization. Nothing here checks: with the values below the chart installs onto a node without /dev/kvm and reports success, and only sandbox runs fail. Confirm /dev/kvm on the node before you start.

Why you install it, and not the platform

Kata is a node-level runtime. It puts binaries on every node, reconfigures containerd, and registers a cluster-scoped RuntimeClass. That makes it cluster infrastructure, on the same footing as your CNI or your CSI driver, and it belongs to whoever owns the cluster.

Three consequences follow, and they are the reason for the split:

It is installed once per cluster, however many deployments share it. The RuntimeClass is a cluster-scoped object, so it cannot belong to one release.
Its upgrades are node maintenance. Installing or upgrading it restarts the container runtime on every node it prepares. That is a window you schedule, not something that should ride along with an application upgrade.
Nodes that join later are handled for you. The chart runs as a DaemonSet, so a node appearing after the install — a replacement for the application node, for instance — is prepared when it joins.

Install

Save the values file

Write this to kata-values.yaml. Every setting is either an upstream default or a deliberate narrowing, and the ones that matter are explained under What these values do.

kata-values.yaml

# Only the Go Cloud Hypervisor shim. This produces RuntimeClass/kata-clh.
shims:
  disableAll: true
  clh:
    enabled: true
    supportedArches:
      - amd64
    allowedHypervisorAnnotations: []
    containerd:
      snapshotter: ""
    dropIn: |
      [hypervisor.clh]
      virtio_fs_extra_args = ["--thread-pool-size=1", "--announce-submounts", "--xattr"]
      kernel_params = "cgroup_no_v1=all systemd.unified_cgroup_hierarchy=1"
      enable_annotations = []
 
defaultShim:
  amd64: clh
 
# Images come from your cluster's ordinary snapshotter.
snapshotter:
  setup: []
 
runtimeClasses:
  enabled: true
  createDefault: false
  overheadEnabled: false
 
monitor:
  enabled: false
 
node-feature-discovery:
  enabled: false
 
priorityClassName: system-node-critical
 
# Pinned and pull-if-absent, so a mirrored or air-gapped registry works.
imagePullPolicy: IfNotPresent
kubectlImage:
  tag: "v1.36.4"

Install the chart

helm install kata-deploy \
  oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy \
  --version 4.1.0 \
  --namespace kube-system \
  -f kata-values.yaml \
  --wait --timeout 25m

The install unpacks Kata onto every node and restarts containerd on each one, so run it in a maintenance window.

Verify

Both commands must return at least one object before you install the platform.

kubectl get runtimeclass kata-clh
kubectl get nodes -l katacontainers.io/kata-runtime=true

The label is applied only after a node's install has completed, so the second command is the one that tells you a node is genuinely ready.

The application expects a runtime class named kata-clh by default, which is what the values above produce. Do not install Kata with env.multiInstallSuffix, which renames it.

Nothing checks this at install time. The platform may install without the sandbox runtime, but it will not operate correctly: agent runs fail, with sandbox pods that never leave Pending. Make sure both commands above pass before you install the platform.

What these values do

Two settings are not optional, because the platform depends on them:

The Go Cloud Hypervisor shim (clh), not clh-runtime-rs. The sandbox reaches each run's control channel through a socket the Go runtime places at a specific path. The Rust runtime lays that state out differently, and runs will not start.
--xattr alongside the upstream default --announce-submounts in virtio_fs_extra_args. Each run's workspace is composed from nested mounts that the guest has to observe, and the guest executes a helper that carries Linux file capabilities, which requires the filesystem daemon to expose security.capability.

The rest narrows a general-purpose chart to what a deployment needs: one shim instead of twenty, no alternative snapshotter, no monitoring sidecar, and no bundled node-feature-discovery, which would collide with an existing installation.

overheadEnabled: false is worth understanding. The chart can advertise a fixed per-pod CPU and memory overhead on the RuntimeClass. The platform already accounts for sandbox cost in its own admission budgets, so leaving it on charges the same capacity twice and reduces how many runs your node admits.

Upgrading Kata

Kata upgrades are yours to schedule, independently of platform upgrades. Reinstalling or upgrading the chart restarts the container runtime on each node it touches, so treat it as node maintenance and pace it with the chart's updateStrategy.

Running more than one deployment on a cluster

Install Kata once, as its own release, independent of any deployment. Every deployment then uses it without owning it.

Do not tie the installation to one deployment's lifecycle. Uninstalling that deployment would take the runtime away from the others.

What this article will cover

Air-gapped installation from a mirrored registry
Gating node scheduling on Kata readiness with startup taints
Troubleshooting a node the chart could not prepare

Cluster and node requirements AWS EKS