diff --git a/docs/installation.md b/docs/installation.md index f54f752cc7..40f800e50b 100644 --- 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. diff --git a/tests/spellcheck/kata-dictionary.txt b/tests/spellcheck/kata-dictionary.txt index 5106f7539b..5fa2d564e2 100644 --- a/tests/spellcheck/kata-dictionary.txt +++ b/tests/spellcheck/kata-dictionary.txt @@ -33,6 +33,7 @@ MDEV MKVP MMDS mmio +mshv NVDIMM OVMF SEV