Skip to main content

Module runtime

Module runtime 

Source
Expand description

CRI runtime service implementation

Provides Kubernetes CRI-aligned APIs for managing pod sandboxes (Kata VMs) and containers. PodSandbox maps to a Kata VM, Container to an OCI container within that VM.

§Architecture

WorkerService (RequestService)
    │
    ├── canonical RuntimeClient contract (`hyprstream-rpc-std`)
    │     ├── run_pod_sandbox()    → Creates Kata VM
    │     ├── create_container()   → Creates container in VM
    │     ├── start_container()    → Starts container
    │     └── exec_sync()          → Executes command
    │
    └── SandboxPool
          ├── Warm pool (pre-created VMs)
          └── Active sandboxes

Re-exports§

pub use backend::SandboxBackend;
pub use backend::SandboxHandle;
pub use exec_mount::ExecMount;
pub use kata_backend::KataBackend;
pub use kata_backend::KataHandle;
pub use nspawn::NspawnBackend;
pub use nspawn::NspawnConfig;
pub use nspawn::NspawnHandle;
pub use selection::backend_injects_9p_socket;
pub use selection::require_9p_socket_capability;
pub use selection::require_fuse_mount_capability;
pub use selection::resolve_backend;
pub use selection::resolve_backend_9p_capable;
pub use selection::BackendCtx;
pub use selection::BackendRegistration;
pub use selection::explain_selection;
pub use selection::BackendCandidate;
pub use sandbox_fs::InjectedMounts;
pub use sandbox_fs::SandboxFs;
pub use sandbox_fs::SandboxFsLocalMount;
pub use sandbox_fs::SandboxFsServer;
pub use sandbox_fs::VFS_SOCKET_NAME;
pub use wanix_workload::import_guest_namespace;
pub use wanix_workload::inject_9p_socket;
pub use wanix_workload::ImportedGuestNamespace;
pub use wanix_workload::Injected9pServer;
pub use wanix_workload::WanixGuestConfig;
pub use wanix_workload::WanixInjection;
pub use wanix_workload::ANN_WANIX_COMMAND;
pub use wanix_workload::ENV_9P_SOCK;
pub use wanix_workload::ENV_GUEST_EXPORT_SOCK;

Modules§

backend
SandboxBackend trait — pluggable sandbox runtime abstraction
exec_mount
/exec/instances/ VFS mount — projects SandboxPool’s active sandboxes as a Plan9 /proc-style tree.
kata_agent
kata-agent ttrpc/vsock client — T1-C (#344) of the Worker GA epic (#341)
kata_backend
KataBackend — Kata Containers VM-based sandbox isolation
nspawn
NspawnBackend — systemd-nspawn based sandbox isolation
sandbox_fs
Per-sandbox VFS composition + serve (FS-D, #365).
selection
Inventory-based sandbox backend registry + fail-closed selection (#507).
spawner
Worker spawner abstraction for process management
wanix_workload
Wanix-guest workload wiring (#506, deliverable 3).

Structs§

AdmissionConfig
Per-Subject / per-group admission quotas + wait-queue bounds + declared local schedulable capacity (#525 P2).
Container
Runtime representation of a container
DenyUnknownGroupValidator
Fail-closed default GroupSelectorValidator: denies every non-empty group selector (no membership source is wired), permits the absent-selector (no-partition) case. This is the production default until a real membership-backed validator is wired — an unverified group can never partition capacity.
EnvelopeContext
Context extracted from a verified SignedEnvelope.
PodSandbox
Runtime representation of a pod sandbox
PoolStats
Pool statistics
SandboxPool
Sandbox pool for warm sandbox management
ServiceHandle
Handle for a running service
StaticGroupMembership
Reference GroupSelectorValidator backed by a static in-memory membership set (group → member Subject keys). Models the authoritative bidirectional-consent membership fact without the PDS/discovery plumbing; a production deployment wires an is_member-backed impl instead.
StatusResponse
Runtime status response (local composite, not in schema).
WorkerService
WorkerService handles requests from the canonical worker contract.

Constants§

ANN_GPU_REQUEST
Annotation key: per-request GPU count demand (a plain non-negative integer string, e.g. "1"). Independent of oci_backend’s existing boolean hyprstream.io/gpu passthrough flag — see module docs, point 4.
ANN_GROUP
Annotation key: the group selector for this request (B′, #921 decision 5). This is not a trusted group claim — it only names which of the groups the verified Subject provably belongs to this request should be partitioned under. A GroupSelectorValidator resolves it against the authoritative membership source; a selector the Subject is not a member of is rejected. See module docs, point 2.
RUNTIME_NAME
CRI runtime name
RUNTIME_VERSION
CRI runtime version

Traits§

GroupSelectorValidator
Resolves an untrusted group selector against the verified Subject’s membership (B′, ratified in #921 decision 5).
RequestService
Trait for RPC services.