guest: add Ubuntu userland support - #116
Draft
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Draft
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Pedro Henrique Penna (ppenna) wants to merge 1 commit into
Conversation
Introduce typed guest descriptors and explicit --guest selection for native and Docker builds, run commands, and correctness workflows while preserving Alpine defaults and artifact names. Build Ubuntu Base 26.04.1 from a repository-owned SHA-256 pin, install a complete locked supplemental .deb closure without executing maintainer scripts, enforce safe archive extraction and sandbox metadata policy, and emit deterministic initramfs and EROFS artifacts with binary-package and helper provenance. Add exact Ubuntu source collection with Launchpad publishing-history fallback for superseded versions, extend release and download packaging, add Docker and CI artifact coverage, move common guest helpers into a distribution-neutral layout, and document both the interactive initramfs and non-root sandbox layer profiles. The OpenVMM submodule and kernel configuration remain unchanged. Validated with the 217-test Python suite, Ruff and Pyright on Linux and Windows targets, ShellCheck and shfmt, deterministic double builds, native Alpine and Ubuntu artifact builds, and local WHP initramfs, lifecycle, SMP, console, networking, HostFs, snapshot, and sandbox execution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6f9e68de-6b8a-4d23-b59e-ce1026001e15
Copilot started reviewing on behalf of
Pedro Henrique Penna (ppenna)
September 18, 2026 18:14
View session
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Verification failures and unresolved artifact determinism, cache, benchmark, and source-provenance gaps remain.
Get a fresh assessment by requesting another Copilot review.
Review effort: Balanced
Findings: 2
Open (8)
What changed in this PR
Adds Ubuntu Base 26.04.1 guest support alongside Alpine while retaining the shared NVX kernel and Alpine defaults.
Changes:
- Adds typed guest selection, Ubuntu artifact builds, and runtime tests.
- Adds deterministic EROFS packaging and corresponding-source collection.
- Integrates Ubuntu artifacts into CI, releases, setup, and documentation.
| File | Description |
|---|---|
| ubuntu/packages.lock.json | Pins supplemental Ubuntu packages. |
| THIRD_PARTY_NOTICES.md | Documents Ubuntu licensing obligations. |
| SOURCE-MANIFEST.json | Records Ubuntu source inputs. |
| scripts/test_nvx_tools.py | Tests guest tooling and source handling. |
| scripts/test_microvm_tests.py | Tests Ubuntu microVM selection. |
| scripts/setup/setup-windows-whp.ps1 | Installs Ubuntu artifacts on Windows. |
| scripts/setup/setup-linux-mshv.sh | Builds and bundles all guests. |
| scripts/nvx.py | Adds guest-aware CLI commands. |
| scripts/nvx_tools/release.py | Packages Ubuntu binaries and sources. |
| scripts/nvx_tools/microvm_tests.py | Adds Ubuntu correctness profiles. |
| scripts/nvx_tools/guests.py | Defines typed guest descriptors. |
| scripts/nvx_tools/common.py | Shares cache and verified-download helpers. |
| scripts/nvx_tools/collect_ubuntu_sources.py | Collects exact Ubuntu sources. |
| scripts/nvx_tools/build.py | Builds Ubuntu initramfs and EROFS artifacts. |
| scripts/nvx_tools/benchmark.py | Supports guest-specific boot markers. |
| README.md | Introduces Ubuntu guest selection. |
| guest/ubuntu/nvx-bashrc | Configures the Ubuntu shell. |
| guest/common/nvx-virtio-restore-probe | Shares virtio restore validation. |
| guest/common/nvx-snapshot | Shares snapshot and restore handling. |
| guest/common/nvx-sandbox-smoke | Validates Ubuntu sandbox execution. |
| guest/common/nvx-reseed.c | Implements restore reseeding. |
| guest/common/nvx-port-io.c | Implements restore port operations. |
| guest/common/nvx-mmio-write.c | Adds MMIO notification support. |
| guest/common/nvx-init-agent | Bootstraps sandbox workloads. |
| guest/common/nvx-identity-probe | Validates workload isolation. |
| guest/common/nvx-hostmount | Mounts virtio-fs shares. |
| guest/common/nvx-exit | Implements guest shutdown. |
| guest/common/nvx-device-io.c | Provides static I/O benchmarking. |
| guest/common/nvx-console-pending.c | Reports pending console input. |
| guest/common/init | Boots Alpine or Ubuntu userland. |
| guest/alpine/nvx-container-launch | Launches Alpine-controlled workloads. |
| guest/alpine/nvx-container-enter | Constructs workload namespaces. |
| docker/Dockerfile | Builds all guest artifact variants. |
| doc/usage.md | Documents new CLI options. |
| doc/setup.md | Updates validation paths. |
| doc/run.md | Documents Ubuntu runtime usage. |
| doc/project-structure.md | Describes the guest layout. |
| doc/distribution.md | Documents Ubuntu source distribution. |
| doc/design/validation.md | Extends validation architecture. |
| doc/design/sandbox-filesystem-and-agent-architecture.md | Updates sandbox helper locations. |
| doc/design/goals.md | Expands guest portability goals. |
| doc/design/code-ownership-map.md | Updates guest ownership paths. |
| doc/design.md | Links the Ubuntu design documentation. |
| doc/ci.md | Documents Ubuntu CI coverage. |
| doc/build.md | Documents Ubuntu build workflows. |
| .github/workflows/ci.yml | Runs Ubuntu guest and sandbox tests. |
| .github/actions/check-quality/action.yml | Checks relocated guest scripts. |
| .github/actions/build-guest-artifacts/action.yml | Builds and caches Ubuntu artifacts. |
| .gitattributes | Enforces guest-source line endings. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| "base_url": "https://cdimage.ubuntu.com/ubuntu-base/releases/26.04/release/ubuntu-base-26.04.1-base-amd64.tar.gz", | ||
| "base_sha256": "a496a960472ce474a59590b8987d3a1135d3cbef1991f3b1abe8cacfea8bf85a", | ||
| "package_lock": "ubuntu/packages.lock.json", | ||
| "package_lock_sha256": "7d1796fa60c067d45bae9bcbd96dc523224515a9a6292925a9fd96f0a0fa78fa", |
| def _build_device_io_helper(work: Path, destination: Path) -> dict[str, str]: | ||
| compiler = require_tool("cc") | ||
| source = REPO_ROOT / "alpine" / "nvx-device-io.c" | ||
| source = REPO_ROOT / "guest" / "common" / "nvx-device-io.c" |
Comment on lines
+48
to
+49
| ALPINE_INPUT_HASH: ${{ hashFiles('guest/common/**', 'guest/alpine/**', 'docker/Dockerfile', 'scripts/nvx_tools/build.py') }} | ||
| UBUNTU_INPUT_HASH: ${{ hashFiles('guest/common/**', 'guest/ubuntu/**', 'ubuntu/**', 'docker/Dockerfile', 'scripts/nvx_tools/build.py', 'scripts/nvx_tools/ubuntu.py') }} |
| ca-certificates \ | ||
| cpio \ | ||
| curl \ | ||
| erofs-utils \ |
Comment on lines
+453
to
+455
| "directory": self_link, | ||
| "index_url": urls_url, | ||
| "index_sha256": metadata_sha256, |
Comment on lines
+488
to
+494
| output = output.resolve() | ||
| packages_root = output / "packages" | ||
| if packages_root.exists(): | ||
| shutil.rmtree(packages_root) | ||
| for generated in (output / "manifest.json", output / "SHA256SUMS"): | ||
| generated.unlink(missing_ok=True) | ||
| packages_root.mkdir(parents=True, exist_ok=True) |
| "virtio-net", | ||
| "workload-identity", | ||
| ) | ||
| UBUNTU_UNSUPPORTED_SCENARIOS = frozenset(("sandbox-blocks", "scratch-snapshot")) |
| root = work / "root" | ||
| if root.exists(): | ||
| shutil.rmtree(root) | ||
| root.mkdir() |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--guestselection for build, run, and correctness workflows while preserving Alpine defaults.debclosure without maintainer-script execution, and emit deterministic initramfs and EROFS artifacts with package/helper provenanceguest/common, retain Alpine-only sandbox entry helpers underguest/alpine, and add the Ubuntu shell-ready and sandbox smoke profilesValidation
python3 -m unittest scripts/test_performance.py scripts/test_nvx_tools.py scripts/test_microvm_tests.py -v— 217 tests passed, 1 skippedpython3 scripts/nvx.py verify, CLI help smoke tests, host inventory tests, and PowerShell syntax parsingScope
This change does not modify the OpenVMM submodule or
kernel/config-microvm. Ubuntu uses the existing NVX kernel and fixed microVM ABI. Systemd remains unsupported for the initial Ubuntu profiles.