feat: run OCI containers as lab devices

[Frando]

Description

Integration tests written against patchbay often need an auxiliary service running alongside the code under test: an ACME test server like Pebble, a database, a real DNS server. These are usually easier to run as a container than to embed. This lets patchbay run one as an ordinary lab node.

A container is a device. Lab::add_container(name, image) returns a builder that mirrors the device builder for wiring (uplink, iface, default_via, mtu) and adds container configuration on top. It creates the device namespace and veth uplink like any device, then runs the image joined to that namespace, so the service is reachable from other lab devices at the container's lab IP.

let pebble = lab
    .add_container("pebble", "ghcr.io/letsencrypt/pebble:latest")
    .uplink(net.id())
    .env("PEBBLE_VA_NOSLEEP", "1")
    .volume_ro(config_dir.join("pebble.json"), "/test/config/pebble.json")
    .args(["-config", "/test/config/pebble.json"])
    .ready_tcp(14000)
    .build()
    .await?;

// Reachable from any lab device.
let directory = format!("https://{}:14000/dir", pebble.ip().unwrap());

The returned Container dereferences to Device, so the device accessors work directly, and it adds container methods: exec, logs, stop, write_file/read_file, and copy_to/copy_from. Volumes come in read-write, read-only, and tmpfs forms. The container is removed when the handle is dropped.

Runtime and requirements

Containers run with podman, which must be on PATH. Podman is daemonless, so the podman run process, forked from inside the device's namespace worker, joins that namespace with --network=host and lands the container on the device's lab IP. Docker cannot do this rootlessly: its daemon runs in a separate namespace, so a docker container would join the daemon's namespace rather than the device's.

Running a container inside patchbay's rootless user namespace needs a full subuid/subgid range, the standard rootless-podman setup: newuidmap/newgidmap on PATH and an /etc/subuid and /etc/subgid entry for the user. The user-namespace bootstrap now maps that range via newuidmap/newgidmap when the host provides it, and falls back to the previous single-uid map otherwise. A single uid cannot unpack image layers or mount overlay; the range can. Router and device networking work either way, so this changes nothing for labs that do not use containers.

Why it took some plumbing

patchbay maps the invoking user to uid 0, so podman would otherwise treat itself as rootful and use unwritable system paths. Two internal but stable environment variables (_CONTAINERS_USERNS_CONFIGURED, _CONTAINERS_ROOTLESS_UID/GID) tell it it is the already-configured rootless namespace, so it uses the user's rootless storage and reuses already-pulled images. The image is pulled on the host before the container starts, because the device namespace has no route to a registry, and the pull runs on a thread with its own mount namespace, since podman makes its storage mounts private and the plain worker threads share the host mount namespace.

Notes and dead ends

Two alternatives to the environment-variable approach turned out not to be worth it, and the reasons are recorded next to the code:

• Running patchbay as a non-zero uid so podman detects rootless on its own. The rootful-versus-rootless storage choice is keyed on euid, not the namespace, so this only trades one variable for a non-root uid that would break patchbay's own uid-0 assumptions.
• Letting podman create its own nested user namespace for the container. The automatic, subuid-driven nesting fails because the inner user has no subuid delegation; an explicit --uidmap 0:0:65536 does work with --network=host, but it is redundant, since patchbay's namespace already maps the full range the container needs.

Making "run in an already-configured user namespace as uid 0" a first-class podman flag is an open upstream request (podman-container-tools/podman#7774).

The API borrows its shape from testcontainers-rs (bind mounts with an access mode, tmpfs, copy in and out) but stays smaller on purpose: ready_tcp covers the common readiness case rather than a full set of wait strategies, which can be added when a service needs them.

Testing

Unit tests cover the run-argument and mount rendering and the container-name sanitizing. Integration tests, gated on podman so they skip where it is absent, run nginx and fetch it from a separate client device, check that a read-only bind mount is visible, and round-trip write_file/read_file and copy_to/copy_from. The full library suite passes with the range-map user namespace, so existing behavior is unchanged.

🤖 Generated with Claude Code