nixos/doc: document systemd-nspawn test containers#479968
Conversation
fbd2cc9 to
bd731a2
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the newly introduced systemd-nspawn backend for the NixOS test driver. The documentation helps developers understand when to use containers versus VMs for tests, configure their systems appropriately, write container-based tests, and debug them.
Changes:
- Adds two example tests demonstrating container functionality (
test-containers.nixandtest-containers-bittorrent.nix) - Implements systemd-nspawn container support in the test driver with a new
NspawnMachineclass alongside the existingQemuMachineclass - Refactors networking and test infrastructure to support both VMs and containers through shared abstractions
- Adds extensive documentation covering container vs. VM trade-offs, configuration options, and debugging approaches
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| nixos/tests/test-containers.nix | Example test demonstrating container networking and VLAN connectivity |
| nixos/tests/test-containers-bittorrent.nix | Complex test showing BitTorrent functionality across containers and VMs |
| nixos/tests/all-tests.nix | Registers the new container tests |
| nixos/modules/virtualisation/qemu-vm.nix | Moves shared networking options to common module |
| nixos/modules/virtualisation/nspawn-container/* | Implements systemd-nspawn container module and run-nspawn Python package |
| nixos/modules/virtualisation/guest-networking-options.nix | Shared networking options for both VMs and containers |
| nixos/modules/testing/test-instrumentation.nix | Disables backdoor for containers (uses nsenter instead) |
| nixos/lib/testing/* | Refactors test infrastructure to support both VMs and containers |
| nixos/lib/test-driver/* | Implements BaseMachine abstraction with QemuMachine and NspawnMachine implementations |
| nixos/doc/manual/development/*.section.md | Comprehensive documentation for writing and debugging container tests |
| nixos/doc/manual/redirects.json | Adds redirects for new documentation sections |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
bd731a2 to
bfdcc7c
Compare
bfdcc7c to
8acd6dc
Compare
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
8acd6dc to
bfdcc7c
Compare
Review dismissed automatically
bfdcc7c to
77a3346
Compare
|
|
||
| - Virtual machines run a separate kernel, which allows testing kernel features | ||
| (kernel modules, etc.). | ||
| - Virtual machines support testing graphical applications on X11. |
There was a problem hiding this comment.
the interactive driver seems to have been relegated to VMs in the documentation. should that be mentioned here as well?
|
not sure if/how this should be part of documentation, but one question coming to mind for me would be, could a single test contain a mix of the two? if so, would that affect whether/how these could interact with one another? |
77a3346 to
f8355f9
Compare
Thank you for the question! I have now added a section covering this. |
f8355f9 to
1cf9f75
Compare
| test script). | ||
|
|
||
| ## Shell access in interactive mode {#sec-nixos-test-shell-access} | ||
| ## Shell access to VMs in interactive mode {#sec-nixos-test-shell-access} |
There was a problem hiding this comment.
while shell_interact may be specific to VMs, use of socat appears relevant with nspawn containers now as well.
it would be good to make sure that the documentation reflects that.
1cf9f75 to
5a00c46
Compare
|
Oops. Is it easy for you to solve conflicts with this base? |
5a00c46 to
c125bc7
Compare
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Not important. It's just some commits from master.
c125bc7 to
4e91a4a
Compare
|
I know it's not a great approach, but let me just merge to unblock all the tests that depend on the NixOS manual. |
|
Certainly feel free to continue reviewing and improving this. |
b512496
|
Actually, it seems like something else got worse by this merge? |
Huh, didn't see that coming (and the CI didn't catch it either ...). Anyways, here's my fix for the errors that I'm seeing in the log: #501294. |
|
The CI doesn't check much, though the |
|
The -small test-set is green again now 🎉 Thanks for quick fixups. |
Ma27
left a comment
There was a problem hiding this comment.
@kmein the one thing I'm missing here is a note reflecting the differences in how the shell in the test node is invoked: #478109 (comment)
This PR adds and adjusts documentation for the newly introduced systemd-nspawn backend for the NixOS test driver (added in #478109). It ensures that developers know how to:
See the relevant sections rendered by running:
xdg-open "file://$(nix-build nixos/release.nix -A manual.x86_64-linux --no-out-link)/share/doc/nixos/index.html#sec-writing-nixos-tests"@NixOS/documentation-team
Things done
passthru.tests.nixpkgs-reviewon this PR. See nixpkgs-review usage../result/bin/.Add a 👍 reaction to pull requests you find important.