github/kata-containers
1
0
Fork 2
mirror of https://github.com/kata-containers/kata-containers.git synced 2026-04-02 18:13:57 +00:00
Code Issues Projects Releases Wiki Activity

docs: Update runtime-rs README with accurate architecture documentation

Browse Source 
Add comprehensive hypervisor support table (Dragonball, QEMU,
Cloud Hypervisor, Firecracker, Remote). Document all runtime handlers
(VirtContainer, LinuxContainer, WasmContainer) and resource types.

List all configuration files including CoCo variants (TDX, SNP, SE).
Add shim-ctl crate to crates table for development tooling reference.
Add Feature Flags section documenting dragonball and cloud-hypervisor
options.

Simplify and restructure content for clarity while preserving technical
accuracy.

Signed-off-by: Alex Lyn <alex.lyn@antgroup.com>
This commit is contained in:
Alex Lyn
2026-03-18 19:10:28 +08:00
committed by Fabiano Fidêncio
parent c96b2034dc
commit 48ef2220e8
1 changed files with 122 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
src/runtime-rs/README.md
View File

@@ -1,131 +1,179 @@
# runtime-rs
## Wath's runtime-rs
## What is runtime-rs
`runtime-rs` is a new component introduced in Kata Containers 3.0, it is a Rust version of runtime(shim). It like [runtime](../runtime), but they have many difference:
`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.
- `runtime-rs` is written in Rust, and `runtime` is written in Go.
- `runtime` is the default shim in Kata Containers 3.0, `runtime-rs` is still under heavy development.
- `runtime-rs` has a completed different architecture than `runtime`, you can check at the [architecture overview](../../docs/design/architecture_3.0).
Key characteristics:
**Note**:
- **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
`runtime-rs` is still under heavy development, you should avoid using it in critical system.
For architecture details, see [Architecture Overview](../../docs/design/architecture_4.0).
## Architecture overview
## Architecture Overview
Also, `runtime-rs` provides the following features:
Key features:
- Turn key solution with builtin `Dragonball` Sandbox, all components in one process
- Async I/O to reduce resource consumption
- Extensible framework for multiple services, runtimes and hypervisors
- Lifecycle management for sandbox and container associated resources
See the [architecture overview](../../docs/design/architecture_3.0)
for details on the `runtime-rs` design.
`runtime-rs` is a runtime written in Rust, it is composed of several crates.
This picture shows the overview about the crates under this directory and the relation between crates.
- **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 overview](docs/images/crate-overview.svg)
Not all the features have been implemented yet, for details please check the [roadmap](../../docs/design/architecture_3.0/README.md#roadmap).
## Crates
The `runtime-rs` directory contains some crates in the crates directory that compose the `containerd-shim-kata-v2`.
| Crate | Description |
|-|-|
| [`shim`](crates/shim)| containerd shimv2 implementation |
| [`service`](crates/service)| services for containers, includes task service |
| [`runtimes`](crates/runtimes)| container runtimes |
| [`resource`](crates/resource)| sandbox and container resources |
| [`hypervisor`](crates/hypervisor)| hypervisor that act as a sandbox |
| [`agent`](crates/agent)| library used to communicate with agent in the guest OS |
| [`persist`](crates/persist)| persist container state to disk |
|-------|-------------|
| [`shim`](crates/shim) | Containerd shim v2 entry point (start, delete, run commands) |
| [`service`](crates/service) | Services including TaskService for containerd shim protocol |
| [`runtimes`](crates/runtimes) | Runtime handlers: VirtContainer (default), LinuxContainer(experimental), WasmContainer(experimental) |
| [`resource`](crates/resource) | Resource management: network, share_fs, rootfs, volume, cgroups, cpu_mem |
| [`hypervisor`](crates/hypervisor) | Hypervisor implementations |
| [`agent`](crates/agent) | Guest agent communication (KataAgent) |
| [`persist`](crates/persist) | State persistence to disk (JSON format) |
| [`shim-ctl`](crates/shim-ctl) | Development tool for testing shim without containerd |
### shim
`shim` is the entry point of the containerd shim process, it implements containerd shim's [binary protocol](https://github.com/containerd/containerd/tree/v1.6.8/runtime/v2#commands):
Entry point implementing [containerd shim v2 binary protocol](https://github.com/containerd/containerd/tree/main/runtime/v2#commands):
- start: start a new shim process
- delete: delete exist a shim process
- run: run ttRPC service in shim
containerd will launch a shim process and the shim process will serve as a ttRPC server to provide shim service through `TaskService` from `service` crate.
- `start`: Start new shim process
- `delete`: Delete existing shim process
- `run`: Run ttRPC service
### service
The `runtime-rs` has an extensible framework, includes extension of services, runtimes, and hypervisors.
Currently, only containerd compatible `TaskService` is implemented.
`TaskService` has implemented the [containerd shim protocol](https://docs.rs/containerd-shim-protos/0.2.0/containerd_shim_protos/),
and interacts with runtimes through messages.
Extensible service framework. Currently implements `TaskService` conforming to [containerd shim protocol](https://docs.rs/containerd-shim-protos/).
### runtimes
Runtime is a container runtime, the runtime handler handles messages from task services to manage containers.
Runtime handler and Runtime instance is used to deal with the operation for sandbox and container.
Runtime handlers manage sandbox and container operations:
Currently, only `VirtContainer` has been implemented.
| Handler | Feature Flag | Description |
|---------|--------------|-------------|
| `VirtContainer` | `virt` (default) | Virtual machine-based containers |
| `LinuxContainer` | `linux` | Linux container runtime (experimental) |
| `WasmContainer` | `wasm` | WebAssembly runtime (experimental) |
### resource
In `runtime-rs`, all networks/volumes/rootfs are abstracted as resources.
All resources abstracted uniformly:
Resources are classified into two types:
- **Sandbox resources**: network, share-fs
- **Container resources**: rootfs, volume, cgroup
- sandbox resources: network, share-fs
- container resources: rootfs, volume, cgroup
[Here](../../docs/design/architecture_3.0/README.md#resource-manager) is a detailed description of the resources.
Sub-modules: `cpu_mem`, `cdi_devices`, `coco_data`, `network`, `share_fs`, `rootfs`, `volume`
### hypervisor
For `VirtContainer`, there will be more hypervisors to choose.
Supported hypervisors:
Currently, built-in `Dragonball` has been implemented. We have also added initial support for `cloud-hypervisor` with CI being added next.
| 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
`agent` is used to communicate with agent in the guest OS from the shim side. The only supported agent is `KataAgent`.
Communication with guest OS agent via ttRPC. Supports `KataAgent` for full container lifecycle management.
### persist
Persist defines traits and functions to help different components save state to disk and load state from disk.
State serialization to disk for sandbox recovery after restart. Stores `state.json` under `/run/kata/<sandbox-id>/`.
### helper libraries
## Build from Source and Install
Some helper libraries are maintained in [the library directory](../libs) so that they can be shared with other rust components.
### Prerequisites
## Build and install
Download `Rustup` and install Rust. For Rust version, see `languages.rust.meta.newest-version` in [`versions.yaml`](../../versions.yaml).
See the
[build from the source section of the rust runtime installation guide](../../docs/install/kata-containers-3.0-rust-runtime-installation-guide.md#build-from-source-installation).
Example for `x86_64`:
```bash
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:
```bash
# 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
```bash
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:
```bash
make USE_BUILTIN_DB=false
```
Specify hypervisor during installation:
```bash
sudo make install HYPERVISOR=qemu
# or
sudo make install HYPERVISOR=cloud-hypervisor
```
## Configuration
`runtime-rs` has the same [configuration as `runtime`](../runtime/README.md#configuration) with some [limitations](#limitations).
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-cloud-hypervisor.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](../runtime/README.md#configuration) for configuration options.
## Logging
See the
[debugging section of the developer guide](../../docs/Developer-Guide.md#troubleshoot-kata-containers).
See [Developer Guide - Troubleshooting](../../docs/Developer-Guide.md#troubleshoot-kata-containers).
## Debugging
See the
[debugging section of the developer guide](../../docs/Developer-Guide.md#troubleshoot-kata-containers).
An [experimental alternative binary](crates/shim-ctl/README.md) is available that removes containerd dependencies and makes it easier to run the shim proper outside of the runtime's usual deployment environment (i.e. on a developer machine).
For development, use [`shim-ctl`](crates/shim-ctl/README.md) to test shim without containerd dependencies.
## Limitations
For Kata Containers limitations, see the
[limitations file](../../docs/Limitations.md)
for further details.
`runtime-rs` is under heavy developments, and doesn't support all features as the Golang version [`runtime`](../runtime), check the [roadmap](../../docs/design/architecture_3.0/README.md#roadmap) for details.
See [Limitations](../../docs/Limitations.md) for details.