Skip to content

microVM: remove the runtime and custom sandbox block roles #556

Closed

Description

Summary

The microVM defines four sandbox block roles: distro, runtime, custom, and scratch. Nothing produces or attaches a runtime or custom layer. Remove both roles, so sandbox storage has a read-only distro layer and writable scratch.

Why

  • No producer. build-distro-layer builds only the Ubuntu distro layer, and the converter that would split images into distro, runtime, and custom is still proposed ("Image conversion" in remaining-production-work.md, which doc: replace doc/design with an architecture-only design guide #529 removed).
  • No consumer. CI, the sandbox lifecycle and managed-exec tests, the snapshot scenarios, and every documentation example attach only distro and scratch. nvx-rs and aci_edge_sandboxes attach no sandbox blocks; they use the blockless managed root.
  • No end-to-end coverage. Outside unit tests, only the sandbox-blocks scenario attaches the two roles, as zero-filled raw images; it checks discovery tokens and read-only flags without mounting anything. No test mounts more than one EROFS lower layer, or captures and restores a snapshot with more than one.
  • Unused ABI surface. The roles cost two virtio-mmio slots, two IRQs, and two shared-status words, plus the matching paths in the snapshot contract and the guest agent.

Where the roles live

OpenVMM (openvmm/ submodule; paths relative to it):

  • openvmm/openvmm_defs/src/microvm.rs: MicrovmSandboxBlockRole::{Runtime, Custom}, the slots at 0xd0004000 (IRQ 12) and 0xd0005000 (IRQ 9), shared-status offsets 0x10 and 0x14, validate_microvm_sandbox_blocks ("at most three read-only layers"), and tests.
  • openvmm/openvmm_entry/src/cli_args/microvm.rs: --microvm-sandbox-block role parsing and the four-block limit.
  • openvmm/openvmm_helpers/src/snapshot/microvm.rs and openvmm/openvmm_entry/src/vm_controller/microvm.rs: manifest role names and the "one to three layers and scratch" capture rule.
  • Guide/src/user_guide/openvmm/run.md and Guide/src/reference/openvmm/management/cli.md.

NVX:

  • guest/common/nvx-init-agent: the runtime and custom mounts, the three-layer limit, and the lowerdir stacking.
  • scripts/nvx_tools/sandbox.py: LAYER_ROLES and the role addresses.
  • scripts/nvx_tools/microvm_tests.py and scripts/nvx_tools/microvm_test_scripts/sandbox-blocks.sh: the sandbox-blocks scenario.
  • scripts/test_nvx_tools.py: test_launch_contract_orders_roles_and_builds_agent_command_line.
  • doc/usage.md and doc/run.md.

Decisions

  • Address layout. Keep scratch (0xd0006000, IRQ 11, status word 0x30018) and the control console where they are, and leave the freed windows, IRQs 9 and 12, and status words 0x30010 and 0x30014 unused. Fixed placement means an omitted device never shifts another; compacting would move scratch and the control console and change every machine contract. The architecture guide in doc: replace doc/design with an architecture-only design guide #529 documents this layout.
  • Existing snapshots. Restore maps manifest role names to the enum, so a snapshot that records runtime or custom would fail with the existing unsupported-role error. Confirm that no retained snapshot or template uses these roles.
  • Image model. The image preparation proposal, which doc: replace doc/design with an architecture-only design guide #529 removed, split curated images into distro, runtime, and custom for cache reuse. Decide whether the converter flattens each image into one distro layer, or whether layering returns together with the converter.

Tasks

  • OpenVMM: remove the Runtime and Custom roles, slots, IRQs, and status words from the CLI, the machine contract, snapshot capture and restore, and the tests; update the Guide.
  • NVX: promote the OpenVMM pin.
  • Guest agent: accept only the distro layer and drop the lowerdir stacking.
  • nvx.py sandbox: accept only --layer distro,....
  • Tests: attach only distro and scratch in sandbox-blocks, check that the freed slots are absent, and update the unit tests.
  • Docs: update doc/usage.md and doc/run.md. The architecture guide in doc/design/ already describes only distro and scratch.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions