Merge pull request #13238 from LandonTClipp/install-guide

docs: Expand installation guide with prereqs and methods
2026-07-16 17:04:14 +00:00 · 2026-07-16 10:40:02 +08:00
parent fe5071ccd2 1f95d6d1fe
commit 7e373f3eae
2 changed files with 257 additions and 39 deletions
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,70 +1,287 @@
 # Installation

-## Helm Chart
+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.

-[helm](https://helm.sh/docs/intro/install/) can be used to install templated kubernetes manifests.
+The recommended install path is the [`kata-deploy` Helm chart](#install-on-kubernetes-with-helm-recommended)
+on a Kubernetes cluster. Pre-built release tarballs and from-source builds are
+also supported.

-### Prerequisites
+## Prerequisites

- **Kubernetes ≥ v1.22** – v1.22 is the first release where the CRI v1 API
-  became the default and `RuntimeClass` left alpha.  The chart depends on those
-  stable interfaces; earlier clusters need `feature‑gates` or CRI shims that are
-  out of scope.
+### Hardware

- **Kata Release 3.12** - v3.12.0 introduced publishing the helm-chart on the
-  release page for easier consumption, since v3.8.0 we shipped the helm-chart
-  via source code in the kata-containers `GitHub` repository.
+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.

- CRI‑compatible runtime (containerd or CRI‑O). If one wants to use the
-  `multiInstallSuffix` feature one needs at least **containerd-2.0** which
-  supports drop-in config files
+**CPU virtualization extensions** must be supported and enabled in the
+firmware/BIOS:

- Nodes must allow loading kernel modules and installing Kata artifacts (the
-  chart runs privileged containers to do so)
+| 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 |

-### `helm install`
+On `x86_64`, confirm the extensions are exposed to the OS (no output means
+virtualization is unavailable):

 ```sh
-# Install directly from the official ghcr.io OCI registry
-# update the VERSION X.YY.Z to your needs or just use the latest
+grep -E -o '(vmx|svm)' /proc/cpuinfo | sort -u
+```

-export VERSION=$(curl -sSL https://api.github.com/repos/kata-containers/kata-containers/releases/latest | jq .tag_name | tr -d '"')
+**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):
+
+```sh
+ls -l /dev/kvm
+```
+
+If `/dev/kvm` is missing on `x86_64`, load the KVM module for your CPU:
+
+```sh
+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:
+
+```sh
+sudo modprobe vhost_vsock
+sudo modprobe vhost_net
+```
+
+To load them automatically on boot:
+
+```sh
+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](https://github.com/kata-containers/kata-containers/blob/main/README.md#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](prerequisites.md) 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`**](https://helm.sh/docs/intro/install/) 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](#install-on-kubernetes-with-helm-recommended) | Kubernetes | **Recommended.** Installs every required artifact and the Kata `RuntimeClass`es on each node; handles upgrades and removal via `helm upgrade` / `helm uninstall`. |
+| [Pre-built release tarball](#install-from-a-pre-built-release-tarball) | Docker, single nodes | Manual install; you are responsible for upgrading and removing the artifacts yourself. |
+| [Build from source](#build-and-install-from-source) | Developers and contributors | Build individual components yourself. |
+
+## Install on Kubernetes with Helm (recommended)
+
+[`helm`](https://helm.sh/docs/intro/install/) installs templated Kubernetes
+manifests. The [Kata Deploy Helm chart](https://github.com/kata-containers/kata-containers/blob/main/tools/packaging/kata-deploy/helm-chart/README.md)
+lays down every Kata binary and artifact required on each node and creates
+the Kata `RuntimeClass` resources.
+
+### Install the chart
+
+```sh
+# 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}"
-
-# See everything you can configure
-$ helm show values "${CHART}" --version "${VERSION}"
+helm install kata-deploy "${CHART}" --version "${VERSION}"
 ```

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

-> **Note:** 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)](helm-configuration.md#deployment-modes-daemonset-vs-job)
-> for details and node-selection options.
+```sh
+helm show values "${CHART}" --version "${VERSION}"
+```

 To see what versions of the chart are available:

 ```sh
-$ helm show chart oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy
+helm show chart "${CHART}"
 ```

-### `helm uninstall`
+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](helm-configuration.md).
+
+!!! 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)](helm-configuration.md#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:

 ```sh
-$ helm uninstall kata-deploy -n kube-system
+kubectl get runtimeclasses
 ```

-During uninstall, Helm will report that some resources were kept due to the
-resource policy (`ServiceAccount`, `ClusterRole`, `ClusterRoleBinding`). This
-is **normal**. A post-delete hook Job runs after uninstall and removes those
-resources so no cluster-wide `RBAC` is left behind.
+### Run a test pod

-## Pre-Built Release
+Schedule a pod against a `runtime-rs` `RuntimeClass` to confirm the install
+works:

-Kata can also be installed using the pre-built releases: https://github.com/kata-containers/kata-containers/releases
+```yaml title="kata-qemu-runtime-rs-test.yaml"
+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"]
+```

-This method does not have any facilities for artifact lifecycle management.
+```sh
+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
+
+```sh
+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](https://github.com/kata-containers/kata-containers/releases).
+
+```sh
+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](#install-from-a-pre-built-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`:
+
+```json title="/etc/docker/daemon.json"
+{
+  "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:
+
+```sh
+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](how-to/how-to-run-docker-with-kata.md).
+
+## Build and install from source
+
+Developers and contributors can build Kata components from source. See the
+[Developer Guide](Developer-Guide.md) for the runtime, agent, guest kernel,
+rootfs/initrd images and hypervisors, and the
+[`runtime-rs` README](https://github.com/kata-containers/kata-containers/blob/main/src/runtime-rs/README.md)
+for the Rust shim including the built-in Dragonball VMM and external
+hypervisor options.
--- a/tests/spellcheck/kata-dictionary.txt
+++ b/tests/spellcheck/kata-dictionary.txt
@@ -33,6 +33,7 @@ MDEV
 MKVP
 MMDS
 mmio
+mshv
 NVDIMM
 OVMF
 SEV