diff --git a/src/runtime-rs/Cargo.lock b/src/runtime-rs/Cargo.lock index a95056d607..204ff508b6 100644 --- a/src/runtime-rs/Cargo.lock +++ b/src/runtime-rs/Cargo.lock @@ -2526,6 +2526,16 @@ dependencies = [ "unix_socket2", ] +[[package]] +name = "shim-ctl" +version = "0.1.0" +dependencies = [ + "common", + "logging", + "runtimes", + "tokio", +] + [[package]] name = "signal-hook-registry" version = "1.4.0" diff --git a/src/runtime-rs/Cargo.toml b/src/runtime-rs/Cargo.toml index 414b707258..1859121459 100644 --- a/src/runtime-rs/Cargo.toml +++ b/src/runtime-rs/Cargo.toml @@ -1,4 +1,5 @@ [workspace] members = [ "crates/shim", + "crates/shim-ctl", ] diff --git a/src/runtime-rs/README.md b/src/runtime-rs/README.md index 89c90966be..973439975d 100644 --- a/src/runtime-rs/README.md +++ b/src/runtime-rs/README.md @@ -120,6 +120,8 @@ See the 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). + ## Limitations For Kata Containers limitations, see the diff --git a/src/runtime-rs/crates/shim-ctl/Cargo.toml b/src/runtime-rs/crates/shim-ctl/Cargo.toml new file mode 100644 index 0000000000..b08e15daac --- /dev/null +++ b/src/runtime-rs/crates/shim-ctl/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "shim-ctl" +version = "0.1.0" +edition = "2021" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +anyhow = "^1.0" +common = { path = "../runtimes/common" } +logging = { path = "../../../libs/logging"} +runtimes = { path = "../runtimes" } +tokio = { version = "1.8.0", features = [ "rt", "rt-multi-thread" ] } + diff --git a/src/runtime-rs/crates/shim-ctl/README.md b/src/runtime-rs/crates/shim-ctl/README.md new file mode 100644 index 0000000000..6e7abdb7e4 --- /dev/null +++ b/src/runtime-rs/crates/shim-ctl/README.md @@ -0,0 +1,51 @@ +### Purpose +`shim-ctl` is a binary to exercise the shim proper without containerd +dependencies. + +The actual Kata shim is hard to execute outside of deployment environments due +to its dependency on containerd's shim v2 protocol. Among others, the +dependency requires having a socket with a remote end that's capable of driving +the shim using the shim v2 `ttrpc` protocol, and a binary for shim to publish +events to. + +Since at least some of the shim v2 protocol dependencies are fairly hard to +mock up, this presents a significant obstacle to development. + +`shim-ctl` takes advantage of the fact that due to the shim implementation +architecture, only the outermost couple of shim layers are +containerd-dependent and all of the inner layers that do the actual heavy +lifting don't depend on containerd. This allows `shim-ctl` to replace the +containerd-dependent layers with something that's easier to use on a +developer's machine. + +### Usage + +After building the binary as usual with `cargo build` run `shim-ctl` as follows. + +Even though `shim-ctl` does away with containerd dependencies it still has +some requirements of its execution environment. In particular, it needs a +Kata `configuration.toml` file, some Kata distribution files to point a bunch +of `configuration.toml` keys to (like hypervisor keys `path`, `kernel` or +`initrd`) and a container bundle. These are however much easier to fulfill +than the original containerd dependencies, and doing so is a one-off task - +once done they can be reused for an unlimited number of modify-build-run +development cycles. + +`shim-ctl` also needs to be launched from an exported container bundle +directory. One can be created by running + +``` +mkdir rootfs +podman export $(podman create busybox) | tar -C ./rootfs -xvf - +runc spec -b . +``` + +in a suitable directory. + +The program can then be launched like this: + +``` +cd /the/bundle/directory +KATA_CONF_FILE=/path/to/configuration-qemu.toml /path/to/shim-ctl +``` + diff --git a/src/runtime-rs/crates/shim-ctl/src/main.rs b/src/runtime-rs/crates/shim-ctl/src/main.rs new file mode 100644 index 0000000000..fd51521738 --- /dev/null +++ b/src/runtime-rs/crates/shim-ctl/src/main.rs @@ -0,0 +1,45 @@ +// Copyright (c) 2022 Red Hat +// +// SPDX-License-Identifier: Apache-2.0 +// + +use anyhow::{Context, Result}; +use common::{ + message::Message, + types::{ContainerConfig, Request}, +}; +use runtimes::RuntimeHandlerManager; +use tokio::sync::mpsc::channel; + +const MESSAGE_BUFFER_SIZE: usize = 8; +const WORKER_THREADS: usize = 2; + +async fn real_main() { + let (sender, _receiver) = channel::(MESSAGE_BUFFER_SIZE); + let manager = RuntimeHandlerManager::new("xxx", sender).await.unwrap(); + + let req = Request::CreateContainer(ContainerConfig { + container_id: "xxx".to_owned(), + bundle: ".".to_owned(), + rootfs_mounts: Vec::new(), + terminal: false, + options: None, + stdin: None, + stdout: None, + stderr: None, + }); + + manager.handler_message(req).await.ok(); +} + +fn main() -> Result<(), Box> { + let runtime = tokio::runtime::Builder::new_multi_thread() + .worker_threads(WORKER_THREADS) + .enable_all() + .build() + .context("prepare tokio runtime")?; + + runtime.block_on(real_main()); + + Ok(()) +}