cellos-host-gvisor 0.5.1

gVisor runsc backend for CellOS — runs cells in user-space syscall-emulated sandboxes for environments without KVM.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

//! gVisor [`CellBackend`] — uses `runsc`, the gVisor OCI runtime, to isolate
//! a cell without `/dev/kvm`.
//!
//! L2-06-5 status: **skeleton**.
//!
//! This backend is targeted at environments where a hardware-virt backend
//! (Firecracker) is unavailable — primarily GKE pods (KVM is gated behind the
//! `kvm` feature flag, and nested virt is paid) and a subset of CI runners
//! (e.g. GitHub `ubuntu-latest` without `/dev/kvm` exposed). gVisor's
//! user-mode kernel (`runsc`) intercepts the workload's syscalls and provides
//! a defence-in-depth boundary that Linux namespaces alone do not.
//!
//! ## Scope of the skeleton
//!
//! The OCI bundle generator and the command-line plumbing for `runsc run` /
//! `runsc kill` / `runsc delete` are stubs that:
//!
//! 1. translate an [`ExecutionCellDocument`] into the on-disk pieces `runsc`
//!    expects (bundle directory containing `config.json` and a `rootfs/`),
//! 2. shell out to `runsc` with the documented argument shape,
//! 3. wait for the container process to exit and surface its exit code.
//!
//! The skeleton is **unit-tested for the bundle generator** (pure function,
//! no `runsc` required) and is gated behind `#[cfg(target_os = "linux")]`
//! because:
//!
//! - `runsc` is Linux-only (it relies on `ptrace`/`KVM`/`systrap` switches
//!   that exist nowhere else),
//! - the OCI runtime spec referenced in `config.json` uses Linux namespaces
//!   directly, so a portable stub would lie about what the backend does.
//!
//! On non-Linux hosts the crate compiles to an empty surface so downstream
//! workspace crates can still `use cellos_host_gvisor::*;` in
//! `cfg(target_os = "linux")` blocks without breaking macOS/dev builds.

#![forbid(unsafe_code)]

// Re-export the bundle generator at the crate root so it is reachable from
// host-independent unit tests on every platform. Everything that talks to a
// real `runsc` binary lives behind `#[cfg(target_os = "linux")]` below.
mod bundle;

pub use bundle::{generate_bundle_config, BundleConfig, BundleConfigError};

#[cfg(target_os = "linux")]
mod backend;

#[cfg(target_os = "linux")]
pub use backend::GVisorCellBackend;