Repository navigation
doc: describe the Azure Linux guest in the design - #457
Merged
Pedro Henrique Penna (ppenna) merged 1 commit intoOct 9, 2026
Merged
Conversation
The design goals named only Alpine and Ubuntu userland although Azure Linux 3.0 is an implemented guest that CI boots on every backend. Add a design chapter for it beside the Ubuntu chapter, index it, and name it in the goals and the README quick start. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Pedro Henrique Penna (ppenna)
added
the
documentation
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The documentation accurately reflects the implemented Azure Linux build, runtime, packaging, and CI behavior.
0 open findings
What changed in this PR
Documents Azure Linux 3.0 as a supported NVX workload guest alongside Alpine and Ubuntu.
Changes:
- Adds an Azure Linux guest design chapter covering build, runtime, provenance, and validation.
- Updates the design index and goals.
- Adds Azure Linux guest selection to the README quick start.
| File | Description |
|---|---|
README.md |
Documents --guest azurelinux. |
doc/guests/azurelinux-guest.md |
Adds the Azure Linux guest architecture chapter. |
doc/design/goals.md |
Names Azure Linux as supported userland. |
doc/design.md |
Links and indexes the new chapter. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Pedro Henrique Penna (ppenna)
deleted the
doc-sync/azurelinux-guest-design
branch
October 9, 2026 22:12
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
The design goals said NVX boots "Alpine or Ubuntu userland", and the README quick start named only Ubuntu as an alternative guest. Azure Linux 3.0 is also an implemented guest:
build-initramfs,build-guest,run,test-microvm,package, anddownloadall support it, and CI boots it on every backend. The design had no chapter for it, while the Ubuntu guest has one.This PR adds an Azure Linux guest support chapter beside the Ubuntu chapter, links it from the design index, and names Azure Linux in the goals and the README quick start.
Changes
doc/design/goals.md: the kernel boots Alpine, Ubuntu, or Azure Linux userland on Linux and Windowsscripts/nvx_tools/guests.py(AZURELINUX_GUEST);python scripts/nvx.py build-guest --help(--guest {alpine,ubuntu,azurelinux,all});.github/workflows/run-nvx-microvm-tests.ymlruns Azure Linux smoke tests on Linux and WindowsREADME.md:--guest azurelinuxselects Azure Linux userland afterdownload.github/actions/package-release/action.ymlpackages releases with--binary-only;scripts/nvx_tools/release.py(_guest_release_inputs,_packaged_guest_artifact_names,_install_release_archive) includes and installs the Azure Linux filesdoc/design.md: the index links the new chapter as item 8 and renumbers the restdoc/guests/azurelinux-guest.md, Role: a workload guest, not sandbox control; no sandbox layer;runrejects--gueston restoredocker/Dockerfile(nonvx-init-agentinstalled);guest/common/init("selected guest cannot act as sandbox control");scripts/nvx_tools/microvm_tests.py(SANDBOX_CONTROL_SCENARIOS,sandbox_control);scripts/nvx_tools/build.py(build_distro_layeraccepts only Ubuntu);scripts/nvx.py(restore rejects a non-default guest)nobodyhome; database and cache removal; reproducible packingdocker/Dockerfile(azurelinux-*stages);scripts/nvx_tools/azurelinux.py(load_package_lock,download_packages);scripts/nvx_tools/build_constants.py(AzureLinuxBuildConstants);scripts/nvx_tools/build.py(build_guestrefuses--native);azurelinux/packages.lock.jsonverifyfails whenSOURCE-MANIFEST.jsondisagrees with the Azure Linux pinsscripts/nvx_tools/release.py(verify_source_tree→_validate_source_manifest_metadata,expected_azurelinux)scripts/nvx_tools/build.py(verify_guest_determinismaccepts only Ubuntu);.github/actions/build-guest-artifacts/action.ymlruns only the Ubuntu determinism target/initflow (time ABI step,nvx_exec, direct managed agent, identity check, boot marker, BusyBox shell); 512 MiB defaultguest/common/init;guest/common/nvx-managed-agent.c(-rootfs = direct);scripts/nvx_tools/guests.py(default_memory_mib=512);doc/run.mddocker/Dockerfile(manifest generation);scripts/nvx_tools/azurelinux.py(input_files,input_sha256);scripts/nvx_tools/release.py(_validate_azurelinux_manifest);doc/distribution.md.github/workflows/run-nvx-microvm-tests.yml("Run Azure Linux guest smoke tests" on Linux and Windows);.github/actions/build-guest-artifacts/action.yml(input-keyed cache);python scripts/nvx.py benchmark --help(no guest option)To stay consistent with open PRs, the chapter links to the Ubuntu chapter's kernel-policy section instead of restating kernel options. It also says "static networking" without naming an IP version, because #455 is changing the kernel's IPv6 support. It does not edit any file that an open PR changes.
The design chapter is based on NVX build and guest sources. It makes no OpenVMM claims beyond linking to the existing cold-boot and machine-ABI chapters. Pinned OpenVMM:
f4566bab0a30324de0a2ac292a65d0081ba319e0.Follow-ups
scripts/setup/README.mdis documentation outsidedoc/. Moving it requires updating links indoc/ci.mdanddoc/setup.md, which open PRs are changing.verify-guest-determinism --helpandbuild-distro-layer --helplistalpineandazurelinux, but both commands reject every guest exceptubuntu.doc/design/validation.mdanddoc/ci.mddescribe the microVM tests as booting "the selected Alpine or Ubuntu initramfs". Both files are touched by open PRs, so I left them alone.doc/openvmm-upstream-roadmap.mdrecords fork tip2728f33eawhile the pin is nowf4566bab0. It is a point-in-time PR strategy snapshot, so refreshing it is a separate task.Validation
python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: 110 tests, OK (1 skipped)doc/design.mdlinks every chapter indoc/design/anddoc/guests/. Result: OKgit diff --check: cleanpython scripts/nvx.py verify: "source tree and submodule metadata are consistent"^(doc/|.*\.md$)