2fe3dacb41
virtio-mem is enabled on s390x, where memory hotplug goes through a
virtio-mem-ccw device set up during VM initialization. That device --
and the later resize -- require a memory hotplug region (a non-zero
maxmem/slots on the QEMU command line).
The runtime-rs command line generator, however, zeroes maxmem/slots
whenever the guest uses the shared /dev/shm memory-backend with a
non-nvdimm rootfs (the s390x case: virtio-blk-ccw rootfs). With no
hotplug region reserved, two things broke on s390x:
* setup_virtio_mem failed VM start with "the configuration is not
prepared for memory devices, consider specifying the maxmem option";
* with virtio-mem unavailable, memory resize fell back to pc-dimm,
which is not a valid device model on s390x, breaking
TestContainerMemoryUpdate:
'pc-dimm' is not a valid device model name
Keep the hotplug region when virtio-mem is enabled, mirroring the Go
runtime which reserves maxmem and hotplugs via virtio-mem-ccw on s390x.
This lets setup_virtio_mem succeed at boot and makes memory resize use
virtio-mem instead of pc-dimm.
Also guard setup_virtio_mem behind QemuCmdLine::has_memory_hotplug_region()
as a defensive fallback: if some configuration still ends up without a
hotplug region, skip virtio-mem setup (like static-sizing arches such as
arm64) rather than failing VM start.
Signed-off-by: Fabiano Fidêncio <ffidencio@nvidia.com>
runtime-rs
What is runtime-rs
runtime-rs is a core component of Kata Containers 4.0. It is a high-performance, Rust-based implementation of the containerd shim v2 runtime.
Key characteristics:
- Implementation Language: Rust, leveraging memory safety and zero-cost abstractions
- Project Maturity: Production-ready component of Kata Containers 4.0
- Architectural Design: Modular framework optimized for Kata Containers 4.0
For architecture details, see Architecture Overview.
Architecture Overview
Key features:
- Built-in VMM (Dragonball): Deeply integrated into shim lifecycle, eliminating IPC overhead for peak performance
- Asynchronous I/O: Tokio-based async runtime for high-concurrency with reduced thread footprint
- Extensible Framework: Pluggable hypervisors, network interfaces, and storage backends
- Resource Lifecycle Management: Comprehensive sandbox and container resource management
Crates
| Crate | Description |
|---|---|
shim |
Containerd shim v2 entry point (start, delete, run commands) |
service |
Services including TaskService for containerd shim protocol |
runtimes |
Runtime handlers: VirtContainer (default), LinuxContainer(experimental), WasmContainer(experimental) |
resource |
Resource management: network, share_fs, rootfs, volume, cgroups, cpu_mem |
hypervisor |
Hypervisor implementations |
agent |
Guest agent communication (KataAgent) |
persist |
State persistence to disk (JSON format) |
shim-ctl |
Development tool for testing shim without containerd |
shim
Entry point implementing containerd shim v2 binary protocol:
start: Start new shim processdelete: Delete existing shim processrun: Run ttRPC service
service
Extensible service framework. Currently implements TaskService conforming to containerd shim protocol.
runtimes
Runtime handlers manage sandbox and container operations:
| Handler | Feature Flag | Description |
|---|---|---|
VirtContainer |
virt (default) |
Virtual machine-based containers |
LinuxContainer |
linux |
Linux container runtime (experimental) |
WasmContainer |
wasm |
WebAssembly runtime (experimental) |
resource
All resources abstracted uniformly:
- Sandbox resources: network, share-fs
- Container resources: rootfs, volume, cgroup
Sub-modules: cpu_mem, cdi_devices, coco_data, network, share_fs, rootfs, volume
hypervisor
Supported hypervisors:
| Hypervisor | Mode | Description |
|---|---|---|
| Dragonball | Built-in | Integrated VMM for peak performance (default) |
| QEMU | External | Full-featured emulator |
| Cloud Hypervisor | External | Modern VMM (x86_64, aarch64) |
| Firecracker | External | Lightweight microVM |
| Remote | External | Remote hypervisor |
The built-in VMM mode (Dragonball) is recommended for production, offering superior performance by eliminating IPC overhead.
agent
Communication with guest OS agent via ttRPC. Supports KataAgent for full container lifecycle management.
persist
State serialization to disk for sandbox recovery after restart. Stores state.json under /run/kata/<sandbox-id>/.
Build from Source and Install
Prerequisites
Download Rustup and install Rust. For Rust version, see languages.rust.meta.newest-version in versions.yaml.
Example for x86_64:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup install ${RUST_VERSION}
rustup default ${RUST_VERSION}-x86_64-unknown-linux-gnu
Musl Support (Optional)
For fully static binary:
# Add musl target
rustup target add x86_64-unknown-linux-musl
# Install musl libc (example: musl 1.2.3)
curl -O https://git.musl-libc.org/cgit/musl/snapshot/musl-1.2.3.tar.gz
tar vxf musl-1.2.3.tar.gz
cd musl-1.2.3/
./configure --prefix=/usr/local/
make && sudo make install
Install Kata 4.0 Rust Runtime Shim
git clone https://github.com/kata-containers/kata-containers.git
cd kata-containers/src/runtime-rs
make && sudo make install
After installation:
- Config file:
/usr/share/defaults/kata-containers/configuration.toml - Binary:
/usr/local/bin/containerd-shim-kata-v2
Install Without Built-in Dragonball VMM
To build without the built-in Dragonball hypervisor:
make USE_BUILTIN_DB=false
Specify hypervisor during installation:
sudo make install HYPERVISOR=qemu
# or
sudo make install HYPERVISOR=clh-runtime-rs
Configuration
Configuration files in config/:
| Config File | Hypervisor | Notes |
|---|---|---|
configuration-dragonball.toml.in |
Dragonball | Built-in VMM |
configuration-qemu-runtime-rs.toml.in |
QEMU | Default external |
configuration-clh-runtime-rs.toml.in |
Cloud Hypervisor | Modern VMM |
configuration-rs-fc.toml.in |
Firecracker | Lightweight microVM |
configuration-remote.toml.in |
Remote | Remote hypervisor |
configuration-qemu-tdx-runtime-rs.toml.in |
QEMU + TDX | Intel TDX confidential computing |
configuration-qemu-snp-runtime-rs.toml.in |
QEMU + SEV-SNP | AMD SEV-SNP confidential computing |
configuration-qemu-se-runtime-rs.toml.in |
QEMU + SEV | AMD SEV confidential computing |
configuration-qemu-coco-dev-runtime-rs.toml.in |
QEMU + CoCo | CoCo development |
See runtime configuration for configuration options.
Logging
See Developer Guide - Troubleshooting.
Debugging
For development, use shim-ctl to test shim without containerd dependencies.
Limitations
See Limitations for details.