kata-containers/docs/installation.md

Installation

Kata Containers ships two runtimes side by side: the legacy Go runtime (src/runtime) and runtime-rs (src/runtime-rs), the Rust implementation of the containerd shim v2. Since the 4.0.0 release runtime-rs is the default and recommended choice; the Go runtime is still shipped and supported.

The recommended install path is the kata-deploy Helm chart on a Kubernetes cluster. Pre-built release tarballs and from-source builds are also supported.

Prerequisites

Hardware

Kata Containers runs on bare metal, or inside a VM that has nested virtualization enabled. The following must be true on every host that runs Kata workloads, regardless of installation method.

CPU virtualization extensions must be supported and enabled in the firmware/BIOS:

Architecture	Virtualization technology
x86_64, amd64	Intel VT-x (vmx), AMD-V (svm)
aarch64 (arm64)	ARM Hyp
ppc64le	IBM Power
s390x	IBM Z & LinuxONE SIE

On x86_64, confirm the extensions are exposed to the OS (no output means virtualization is unavailable):

grep -E -o '(vmx|svm)' /proc/cpuinfo | sort -u

KVM must be available: the /dev/kvm device has to exist and be accessible to the user that runs the Kata shim (root, or a member of the kvm group):

ls -l /dev/kvm

If /dev/kvm is missing on x86_64, load the KVM module for your CPU:

sudo modprobe kvm_intel   # Intel hosts
sudo modprobe kvm_amd     # AMD hosts

!!! tip "Microsoft Hypervisor (Hyper-V / Azure)" On hosts backed by the Microsoft Hypervisor — including nested Linux VMs on Windows and some Azure instance types — KVM is not available and the equivalent device is /dev/mshv. You then need a VMM with mshv support, such as Cloud Hypervisor's mshv backend used by the clh-azure / clh-azure-runtime-rs runtime classes.

Nested virtualization is required when the host is itself a VM: the underlying hypervisor must expose the CPU virtualization extensions to the guest (for example a host-passthrough or host-model CPU, with nesting enabled on the bare-metal host).

Host kernel modules for vhost must be loaded. Kata uses VSOCK for the communication channel between the runtime and the guest agent (vhost_vsock provides /dev/vhost-vsock); vhost_net is needed for networking:

sudo modprobe vhost_vsock
sudo modprobe vhost_net

To load them automatically on boot:

printf 'vhost_vsock\nvhost_net\n' | sudo tee /etc/modules-load.d/kata-containers.conf

For the full list of supported platforms, see the hardware requirements.

Software

Which of these you need depends on the install method you pick:

• Kubernetes ≥ v1.22 — first release where the CRI v1 API became the default and RuntimeClass left alpha. Earlier clusters need feature gates or CRI shims that are out of scope for this guide.
• CRI-compatible container runtime (containerd or CRI-O). containerd v2.1.x or newer is recommended; the multiInstallSuffix feature and drop-in config merging require containerd v2.0+. See prerequisites for a detailed containerd setup.
• Kata Containers ≥ 3.12 if you install via Helm — v3.12.0 is the first release that publishes the Helm chart on the releases page.
• helm for the Kubernetes install method.
• Docker v26+ if you want to run Kata Containers directly with Docker.

Choosing an installation method

Method	Best for	Notes
Kata Deploy Helm chart	Kubernetes	Recommended. Installs every required artifact and the Kata RuntimeClasses on each node; handles upgrades and removal via helm upgrade / helm uninstall.
Pre-built release tarball	Docker, single nodes	Manual install; you are responsible for upgrading and removing the artifacts yourself.
Build from source	Developers and contributors	Build individual components yourself.

Install on Kubernetes with Helm (recommended)

helm installs templated Kubernetes manifests. The Kata Deploy Helm chart lays down every Kata binary and artifact required on each node and creates the Kata RuntimeClass resources.

Install the chart

# Pick the version you want to install, or use the latest release.
export VERSION=$(curl -sSL https://api.github.com/repos/kata-containers/kata-containers/releases/latest | jq -r .tag_name)
export CHART="oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy"

helm install kata-deploy "${CHART}" --version "${VERSION}"

This installs the kata-deploy DaemonSet and the default Kata RuntimeClass resources on your cluster. To see everything you can configure:

helm show values "${CHART}" --version "${VERSION}"

To see what versions of the chart are available:

helm show chart "${CHART}"

For the full set of configuration options (shim selection, custom runtimes, node selectors, TEE shims, drop-in configuration files and more), see the Helm configuration document.

!!! note "Deployment modes: DaemonSet vs Job" The DaemonSet is the default install model, but it is no longer the only one. You can instead install Kata via short-lived, staged per-node Jobs (no always-on component on the node) by setting deploymentMode: job. See Deployment Modes (DaemonSet vs Job) for details and node-selection options.

Use a Kata RuntimeClass

The chart creates one RuntimeClass per enabled shim. runtime-rs-based runtimes use the -runtime-rs suffix; kata-dragonball (the built-in Dragonball VMM) is runtime-rs only:

RuntimeClass	Hypervisor	Runtime
kata-qemu-runtime-rs	QEMU	runtime-rs
kata-clh-runtime-rs	Cloud Hypervisor	runtime-rs
kata-dragonball	Dragonball (built-in)	runtime-rs
kata-qemu	QEMU	Go runtime (deprecated)

List the runtime classes available on your cluster:

kubectl get runtimeclasses

Run a test pod

Schedule a pod against a runtime-rs RuntimeClass to confirm the install works:

apiVersion: v1
kind: Pod
metadata:
  name: kata-runtime-rs-test
spec:
  runtimeClassName: kata-qemu-runtime-rs
  containers:
    - name: test
      image: quay.io/libpod/ubuntu:latest
      command: ["uname", "-r"]

kubectl apply -f kata-qemu-runtime-rs-test.yaml
kubectl logs kata-runtime-rs-test

The kernel version printed is the Kata guest kernel, normally different from the host kernel (uname -r) — confirming the workload ran inside a lightweight VM.

Uninstall

helm uninstall kata-deploy -n kube-system

During uninstall, Helm reports that some cluster-wide resources (ServiceAccount, ClusterRole, ClusterRoleBinding) were kept due to the resource policy. This is normal: a post-delete hook Job removes them so no cluster-wide RBAC is left behind.

Install from a pre-built release tarball

When you are not using Kubernetes — for example to run Kata Containers with Docker — install Kata from a pre-built release tarball.

Download the archive for your architecture from the releases page.

export VERSION=$(curl -sSL https://api.github.com/repos/kata-containers/kata-containers/releases/latest | jq -r .tag_name)
export ARCH=amd64 # or arm64, s390x, ppcle64 etc

curl -fsSL -o kata-static.tar.zst \
  "https://github.com/kata-containers/kata-containers/releases/download/${VERSION}/kata-static-${VERSION}-${ARCH}.tar.zst"

# The archive uses an /opt/kata/ prefix.
sudo tar -xvf kata-static.tar.zst -C /

The release installs both runtimes side by side:

Path	Runtime
/opt/kata/runtime-rs/bin/containerd-shim-kata-v2	runtime-rs (recommended)
/opt/kata/bin/containerd-shim-kata-v2	Go runtime

Packaged configuration files live under /opt/kata/share/defaults/kata-containers/. The runtime-rs configurations use the -runtime-rs suffix (for example configuration-qemu-runtime-rs.toml), and configuration-dragonball.toml selects the built-in Dragonball VMM.

Use Kata Containers with Docker

Docker v26+ can launch containers with the Kata shim directly. Kata support with Docker is tested with QEMU as the VMM. First, install Kata from a release tarball, then register a Kata runtime in the Docker daemon configuration. To use runtime-rs, point Docker at the runtime-rs shim and select a runtime-rs configuration with ConfigPath:

{
  "runtimes": {
    "kata": {
      "runtimeType": "/opt/kata/runtime-rs/bin/containerd-shim-kata-v2",
      "options": {
        "ConfigPath": "/opt/kata/share/defaults/kata-containers/runtime-rs/configuration-qemu-runtime-rs.toml"
      }
    }
  }
}

!!! note "About ConfigPath" ConfigPath selects which configuration the shim loads (for example configuration-qemu-runtime-rs.toml for QEMU, or configuration-dragonball.toml for the built-in Dragonball VMM). If you omit it, the shim falls back to its default search path, where /etc/kata-containers/configuration.toml takes precedence over the packaged defaults.

Restart the Docker daemon and launch a Kata container:

sudo systemctl restart docker
docker run --runtime kata -it --rm ubuntu:24.04 uname -r

The kernel printed is the Kata guest kernel, normally different from the host's.

!!! warning "Docker-in-Docker" Running docker inside a Kata Container requires extra care. See How to run Docker in Docker with Kata Containers.

Build and install from source

Developers and contributors can build Kata components from source. See the Developer Guide for the runtime, agent, guest kernel, rootfs/initrd images and hypervisors, and the runtime-rs README for the Rust shim including the built-in Dragonball VMM and external hypervisor options.