mirror of
https://codeberg.org/Toasterson/solstice-ci.git
synced 2026-04-10 13:20:41 +00:00
d6c2c3662c
Plans: - 001: vm-manager migration (completed) - 002: runner-only architecture (active) Decision records (ADRs): - 001: Runner-only architecture — retire webhooks + logs service - 002: Direct QEMU over libvirt - 003: Ephemeral SSH keys with opt-in debug access - 004: User-mode (SLIRP) networking for VMs
35 lines
1.6 KiB
Markdown
35 lines
1.6 KiB
Markdown
# ADR-004: User-Mode (SLIRP) Networking for VMs
|
|
|
|
**Date:** 2026-04-07
|
|
**Status:** Accepted
|
|
**Deciders:** Till Wegmueller
|
|
|
|
## Context
|
|
|
|
The orchestrator needs network access to VMs for SSH (uploading runner binary, executing commands). Two options:
|
|
|
|
1. **TAP with bridge** — VM gets a real IP on a bridge network (e.g., virbr0). Requires NET_ADMIN capability, host bridge access, and TAP device creation. IP discovery via ARP/DHCP lease parsing.
|
|
|
|
2. **User-mode (SLIRP)** — QEMU provides NAT via user-space networking. VM gets a private IP (10.0.2.x). SSH access via host port forwarding (`hostfwd=tcp::{port}-:22`). No special capabilities needed.
|
|
|
|
## Decision
|
|
|
|
Use user-mode (SLIRP) networking with deterministic SSH port forwarding.
|
|
|
|
Port assignment: `10022 + (hash(vm_name) % 100)` — range 10022-10122.
|
|
|
|
Guest IP is always `127.0.0.1` from the orchestrator's perspective.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- **Container-friendly**: no NET_ADMIN, no bridge access, no host configuration
|
|
- **Trivial IP discovery**: always `127.0.0.1` with a known port
|
|
- **No host bridge dependency**: works on any host with just `/dev/kvm`
|
|
- **Network isolation**: VMs cannot reach each other or the host network directly
|
|
|
|
### Negative
|
|
- **Port collision risk**: with 100 ports and concurrent VMs, hash collisions are possible (mitigated by UUID-based VM names having good hash distribution)
|
|
- **No inbound connections**: external services cannot reach the VM directly (not needed for CI)
|
|
- **SLIRP performance**: slightly slower than TAP for network-heavy workloads (acceptable for CI)
|
|
- **No VM-to-VM communication**: VMs are fully isolated (acceptable for CI)
|