Repository navigation
Snapshot/restore workstream, stage 1: templates and clones in the shared libraries, on today's OpenVMM #834
Description
Parent: #833. Needs: from the NVX library wiring workstream (#816): the PRs of #822 and #805 that the table below lists, and #860's PR 1. They come before the VM work of #841 and the later PRs.
Goal. nvx::guest and nvx::host deliver platform clones on the OpenVMM that NVX pins today: templates captured into a store, and clones restored from it with their own image, upper, export, network settings and identity. The in-repo test adapter proves them through public APIs and its own framing, on KVM, MSHV and WHP. NVX's own adapter gets them in stage 5 (#837), with stage 3's features (#836) from the start.
Interim rules. Today's OpenVMM imposes five rules. Each stage 3 item removes one:
| Rule | Removed by |
|---|---|
| Images are exactly the placeholder's length. The host library refuses any other length before launch. | #848 |
| Tmpfs clones get a sparse scratch file each, of the template's scratch length. The host library creates it in the clone's private directory, and removes it at teardown. | #848 |
| CPUs: all C online in the template (B = C), and one template per CPU count. Clones get no CPU target. | #849 |
| Network: templates without a NIC, or one template per network policy, with the policy's identity in the key. Clones get no ingress, host loopback or forwards, so listener publication stays off. | #850 |
Exports: at most one directory per clone, which the restore passes as the dormant slot's one --mount. An export plan with several children, or a file child, is refused before launch. |
#857 |
The host connects after OpenVMM's restore-ready event. That's the final design, not an interim rule.
What stage 1 needs from #816. #822 makes the test adapter run cold sandboxes end to end, in stacked PRs, with #805's executions. #860 gives a layered root its resolver, and runtime binds that a teardown can remove. Clones build on these PRs:
| PR | Provides | The PRs that wait for it |
|---|---|---|
| #822's PR 2 | Staged images, the adapter plan and the checked handoff | #841's PR 3, and #844's PR 5: template and clone launches in VMs |
| #822's PR 5 | The export as a mapping source, in nvx::guest |
#845's PR 3 |
| #822's PR 6 | Ready, and the guest's order, in the adapter's framing | #843's PR 3: Activate in the same framing |
| #822's PR 7 | The host's sequence: Ready, the mapping table, Start | #844's PRs 3 and 5 |
| #822's PR 8 | Mapping tables in VMs | #846's PR 1 |
| #822's PR 11 | Network policy in VMs | #846's PR 2: a template per policy; #845's DNS and proxy, in VMs |
| #805's PR 3 | Executions in VMs, with a sandbox-wide or per-execution identity | #844's PR 5, with #843's VM case "no workload before Ready"; #847's PR 2: template run |
| #860's PR 1 | The resolver bind, and removable runtime binds | #845's PRs 2 and 3 |
None of these needs another issue of #816, so that workstream does them first. Nothing else in stages 1 to 3 needs it: #838 defines Ready's activation, which #821 reuses, and the compatibility key takes the guest's build identity from the adapter. #822's consumer-contract scenarios (#859) don't block this stage.
PRs, in order. Each issue splits its work into stacked PRs ("PR 1 of 3", and so on) and gives each PR's own needs. The steps group them; within a step, separate stacks proceed in parallel:
| Step | Stacked PRs | Delivers |
|---|---|---|
| 1. Without a VM, alongside #822 | #838's PRs 1 to 3; #839's PRs 1 to 4; #840's PR 1; #842's PR 1 | The activation record and Ready's activation; the key, the store, leases and the supervisor seam; capture preparation; the owned seed |
| 2. Templates | #841's PRs 1 and 2 (PR 1 can start once #839's PR 1 lands); #840's PR 2; then #841's PR 3 | Template lowering, capture and publication; template mode in the test adapter's guest; captures in VMs |
| 3. First clones | #842's PRs 2 and 3; #843's PRs 1 to 3; #844's PRs 1 to 4; then #844's PR 5 | Repair, Activate and clone restore through Start; EROFS clones over tmpfs and scratch, with memory targets, in VMs |
| 4. Every format, exports and network | #845's PRs 1 to 3; then #846's PRs 1 and 2 | GPT clones, the fresh-scratch check, the workload view; one export with MAPS; network templates |
| 5. Completion | #847's PRs 1 and 2 | The test adapter's template and clone operations, and the stage's consolidated suite |
Only the PRs in that table's last column wait for #816; the others need neither it nor a VM.
Boundaries:
- nvx-rs provides the mechanisms. The adapter decides authorization, image resolution, the store's location and eviction, and when to capture.
- The guest operations don't require PID 1. The test adapter's guest calls them under its own init; NVX's init calls them in stage 5.
- The test adapter uses documented public APIs only, with default features off and its own lockfile.
- A failure at any step tears down the VM. There is no cold fallback, and capture and restore hash no large content.
Tests. Each PR's tests land with it. Every clone scenario is named in the adapter's CI hook, and runs on KVM, MSHV and WHP.
Acceptance. The stage is complete when every PR above is merged and its tests pass with the test adapter on KVM, MSHV and WHP, in CI, under the interim rules.
Guide. Each PR updates the guide's sections that it changes (#591's numbering), and the guide documents the interim rules until stage 3 removes them.
Activity
[-]Platform clones, stage 1: templates and clones in the shared libraries, on today's OpenVMM[/-][+]Snapshot/restore workstream, stage 1: templates and clones in the shared libraries, on today's OpenVMM[/+]