Monorepo for Tangled
spindle/microvm,docs: document devices needed and running in containers better
Signed-off-by: dawn <dawn@tangled.org>
+18
-5
+14
-2
docs/DOCS.md
+14
-2
docs/DOCS.md
···
1555
1555
used to sandbox guest networking.
1556
1556
- `/dev/kvm`: for hardware acceleration (unless you disable
1557
1557
KVM with `SPINDLE_MICROVM_PIPELINES_ENABLE_KVM=false`).
1558
-
- `/dev/vhost-vsock`: the guest agent talks to spindle over
1559
-
vsock.
1558
+
- `/dev/vhost-vsock`: used by QEMU to enable guest-to-host vsock
1559
+
communication.
1560
+
- `/dev/vsock`: used by spindle on the host to listen on vsock ports
1561
+
and accept guest agent connections.
1562
+
- `/dev/net/tun`: required by `slirp4netns` to set up tap devices
1563
+
for sandboxed guest networking.
1560
1564
1561
1565
On NixOS, the [spindle
1562
1566
module](https://tangled.org/tangled.org/core/blob/master/nix/modules/spindle.nix)
1563
1567
puts `qemu`, `e2fsprogs`, `slirp4netns`, `iproute2` and
1564
1568
`util-linux` on the service's `PATH` for you.
1569
+
1570
+
#### Container virtualization
1571
+
1572
+
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:
1573
+
1574
+
- `/dev/vsock`, `/dev/vhost-vsock`, `/dev/kvm`, and `/dev/net/tun` mapped from the host.
1575
+
- `NET_ADMIN` and `SYS_ADMIN` capabilities to manage network namespaces and mounts inside the container.
1576
+
- Relaxed seccomp filters (e.g., `seccomp=unconfined`) and SELinux/AppArmor containment if they restrict namespace creation or device access.
1565
1577
1566
1578
#### Building images
1567
1579
+4
-3
spindle/engines/microvm/README.md
+4
-3
spindle/engines/microvm/README.md
···
72
72
and right before launch we also check the referenced files actually exist on
73
73
disk and that the host has the commands we need: `mkfs.ext4` for volume
74
74
formatting, plus whatever the selected runner requires. For QEMU that's the QEMU
75
-
binary for the spec's arch, `/dev/vhost-vsock`, `/dev/kvm` (if KVM is enabled),
76
-
and the `ip`, `mount`, `slirp4netns`, `unshare` toolchain when the image has
77
-
network interfaces.
75
+
binary for the spec's arch, `/dev/vhost-vsock` (for guest vsock configuration),
76
+
`/dev/vsock` (for host listener sockets), `/dev/kvm` (if KVM is enabled), `/dev/net/tun`
77
+
(for guest networking), and the `ip`, `mount`, `slirp4netns`, `unshare` toolchain when the
78
+
image has network interfaces.
78
79
79
80
## microVM lifecycle
80
81