diff --git a/src/runtime-rs/README.md b/src/runtime-rs/README.md index f626ebef22..fe6f8e10dc 100644 --- a/src/runtime-rs/README.md +++ b/src/runtime-rs/README.md @@ -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//`. -### 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.