Learn Kata Containers - Installation & Setup

#Introduction

It's time for your first real action: installing Kata Containers. In episode 3 we'll walk through three installation paths — the release tarball for a single node, kata-deploy for an entire Kubernetes cluster, and a build from source for those of you who want to understand it deeply. Then we'll verify the installation with kata-runtime check and kata-runtime kata-check.

Episode 2 gave you the architecture map. Now we're placing the components onto the node. Make sure the episode 0 prerequisites are met — especially /dev/kvm — because without hardware acceleration, every installation path will end with a hypervisor that can't boot.

#Path 1: Release Tarball

The most direct way for a single node is to download the release tarball from the official GitHub release page. The tarball contains the kata-runtime binary, containerd-shim-kata-v2, the hypervisor, the guest kernel, and the configuration. Grab the latest stable version:

wget https://github.com/kata-containers/kata-containers/releases/download/4.0.0/kata-static-4.0.0-x86_64.tar.xz
tar -xvf kata-static-4.0.0-x86_64.tar.xz -C /

tar -xvf ... -C / extracts all the components to the standard locations /usr/local/bin, /usr/share, and /etc/kata-containers. Adjust the file name to your architecture — x86_64, aarch64, ppc64le, or s390x.

Note that the tarball extracts to the root directory — make sure you understand what's being installed before running it on a production node. For container environments, extract to a dedicated directory and add it to PATH:

mkdir -p /opt/kata
tar -xvf kata-static-4.0.0-x86_64.tar.xz -C /opt/kata
export PATH=/opt/kata/usr/local/bin:$PATH

#Path 2: kata-deploy with a Helm Chart

For Kubernetes clusters with many nodes, manual installation isn't practical. kata-deploy solves this problem: it runs the installation on every node automatically, including injecting the configuration into containerd and creating the RuntimeClass.

The modern way to use it is through the Helm chart from the official OCI registry:

helm install kata-deploy oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy \
  --namespace kube-system \
  --set defaultRuntimes=kata

helm install kata-deploy oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy pulls the chart from Kata's official OCI registry and deploys a DaemonSet to all nodes. The defaultRuntimes=kata option sets the default runtime the cluster will use.

kata-deploy can also be run as a DaemonSet directly from the GitHub manifest if you're not using Helm:

kubectl apply -f https://raw.githubusercontent.com/kata-containers/kata-containers/main/tools/packaging/kata-deploy/kata-deploy/base/kata-deploy.yaml
kubectl -n kube-system get ds kata-deploy --wait

kubectl -n kube-system get ds kata-deploy --wait blocks until all nodes have finished installing Kata. To remove kata-deploy later, use kubectl delete ds kata-deploy — the Kata binaries remain on the nodes after the DaemonSet is deleted.

#Path 3: Build from Source

To understand things deeply or test changes, build from source. Kata uses Yocto/Buildroot to build the guest image, and its own build system for the runtime. The general requirements: Go (for the classic runtime), the Rust toolchain (for runtime-rs), and build dependencies:

git clone https://github.com/kata-containers/kata-containers.git
cd kata-containers/src/runtime-rs
make
make install

make && make install in the src/runtime-rs directory builds the Rust runtime and installs it on the system. Building from source takes time and demands a complete toolchain — for production, paths 1 and 2 are far more practical. Only use a source build if you're contributing or chasing an experimental version.

#Verifying the Installation

After installing, verify that all components are in place correctly. The first command you should master:

kata-runtime version
kata-runtime check

kata-runtime version displays the runtime version and build components. kata-runtime check is a comprehensive verification command: it checks the required binaries, kernel modules, hardware acceleration, and environment readiness. A healthy output will show System is capable of running Kata Containers.

A more specific related command:

kata-runtime kata-check

kata-runtime kata-check checks whether the host kernel supports all of Kata's requirements — including virtualization features, modules, and /dev/kvm. If any component fails, the output points directly at the problematic item, for example a host kernel that doesn't support a certain feature.

#Container Runtime Configuration

So Kubernetes can use Kata, containerd needs to know a runtime named Kata exists. Open /etc/containerd/config.toml and add a runtimes block for the Kata shim:

/etc/containerd/config.toml

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.kata]
  runtime_type = "io.containerd.kata.v2"
  privileged_without_host_devices = true
  pod_annotations = ["io.katacontainers.*"]
 
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
  runtime_type = "io.containerd.runc.v2"

runtime_type = "io.containerd.kata.v2" tells containerd that the kata runtime is handled by containerd-shim-kata-v2. After changing this file, restart containerd: systemctl restart containerd. kata-deploy does this configuration automatically when it runs.

#Verifying the RuntimeClass

Once containerd knows the Kata runtime, we prepare the RuntimeClass in the cluster. Note that kata-deploy creates this RuntimeClass automatically. For a manual setup:

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

handler: kata must match the runtime name in the containerd configuration. This RuntimeClass will be used in episode 4 to run your first pod. The other RuntimeClass names — kata-clh, kata-fc, kata-qemu-coco-dev — will be discussed under their respective topics.

#Conclusion

What you should take away:

• Release tarball for a single node; kata-deploy Helm chart for a full cluster.
• Official Helm chart: oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy.
• Build from source only for development, not production.
• kata-runtime check and kata-runtime kata-check verify KVM and hypervisor readiness.
• containerd needs to be configured to know the Kata runtime through shim v2.
• The kata RuntimeClass connects pods to the Kata runtime.

In the next episode, episode 4, we'll run the first workload in Kubernetes — understanding the Kata RuntimeClass in full (kata, kata-clh, kata-fc, kata-qemu-coco-dev), creating a pod with spec.runtimeClassName, and verifying that the application process really runs inside the microVM, not on the host.