From e7c20c9117afaba5765921e249bb473a5d336596 Mon Sep 17 00:00:00 2001 From: dawn Date: Tue, 30 Jun 2026 21:01:57 +0300 Subject: [PATCH] spindle/microvm,docs: document devices needed and running in containers better Signed-off-by: dawn --- docs/DOCS.md | 16 ++++++++++++++-- spindle/engines/microvm/README.md | 7 ++++--- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/DOCS.md b/docs/DOCS.md index bd28cb0e..947c3390 100644 --- a/docs/DOCS.md +++ b/docs/DOCS.md @@ -1555,14 +1555,26 @@ clear error. You'll need: used to sandbox guest networking. - `/dev/kvm`: for hardware acceleration (unless you disable KVM with `SPINDLE_MICROVM_PIPELINES_ENABLE_KVM=false`). -- `/dev/vhost-vsock`: the guest agent talks to spindle over - vsock. +- `/dev/vhost-vsock`: used by QEMU to enable guest-to-host vsock + communication. +- `/dev/vsock`: used by spindle on the host to listen on vsock ports + and accept guest agent connections. +- `/dev/net/tun`: required by `slirp4netns` to set up tap devices + for sandboxed guest networking. On NixOS, the [spindle module](https://tangled.org/tangled.org/core/blob/master/nix/modules/spindle.nix) puts `qemu`, `e2fsprogs`, `slirp4netns`, `iproute2` and `util-linux` on the service's `PATH` for you. +#### Container virtualization + +Running `spindle` inside a container (e.g., Docker, Podman, or LXD) requires passing host device nodes into the container and granting the runtime additional privileges. Because spindle uses nested namespaces (`unshare`) and helper tools (`slirp4netns`), the container configuration will require: + +- `/dev/vsock`, `/dev/vhost-vsock`, `/dev/kvm`, and `/dev/net/tun` mapped from the host. +- `NET_ADMIN` and `SYS_ADMIN` capabilities to manage network namespaces and mounts inside the container. +- Relaxed seccomp filters (e.g., `seccomp=unconfined`) and SELinux/AppArmor containment if they restrict namespace creation or device access. + #### Building images Images are built with Nix. The flake exposes packages for the diff --git a/spindle/engines/microvm/README.md b/spindle/engines/microvm/README.md index b2b0efa8..fb9eb925 100644 --- a/spindle/engines/microvm/README.md +++ b/spindle/engines/microvm/README.md @@ -72,9 +72,10 @@ The spec is validated at resolve time (required fields, positive sizes etc.), and right before launch we also check the referenced files actually exist on disk and that the host has the commands we need: `mkfs.ext4` for volume formatting, plus whatever the selected runner requires. For QEMU that's the QEMU -binary for the spec's arch, `/dev/vhost-vsock`, `/dev/kvm` (if KVM is enabled), -and the `ip`, `mount`, `slirp4netns`, `unshare` toolchain when the image has -network interfaces. +binary for the spec's arch, `/dev/vhost-vsock` (for guest vsock configuration), +`/dev/vsock` (for host listener sockets), `/dev/kvm` (if KVM is enabled), `/dev/net/tun` +(for guest networking), and the `ip`, `mount`, `slirp4netns`, `unshare` toolchain when the +image has network interfaces. ## microVM lifecycle -- 2.51.2