mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-20 06:00:06 +08:00
Drew Newberry
910d3f09f2
* feat(vm): boot sandboxes from ext4 root disks * feat(vm): boot sandboxes with writable overlay disk * fix(sandbox): improve sandbox provisioning behavior * fix(vm): repair sandbox image provisioning * fix(vm): clean up rebase fallout * perf(vm): cache empty overlay images * perf(vm): skip repeated sandbox ownership repair * fix(vm): address lifecycle review issues * fix(vm): repair gateway vm startup * wip
75 lines
2.6 KiB
Markdown
75 lines
2.6 KiB
Markdown
# VM Driver Runtime
|
|
|
|
> Status: Experimental. VM support is under active development and may change.
|
|
|
|
This directory owns the pinned runtime inputs for `openshell-driver-vm`:
|
|
|
|
```text
|
|
runtime/
|
|
pins.env
|
|
kernel/
|
|
openshell.kconfig
|
|
```
|
|
|
|
`openshell-driver-vm` embeds libkrun, libkrunfw, gvproxy, umoci for guest-side
|
|
OCI image unpacking, and the bundled `openshell-sandbox` supervisor.
|
|
|
|
## Why
|
|
|
|
The stock `libkrunfw` kernel does not include the bridge, netfilter,
|
|
conntrack, cgroup, seccomp, and Landlock features the sandbox supervisor needs
|
|
inside each microVM. `kernel/openshell.kconfig` extends the libkrunfw kernel so
|
|
VM sandboxes can run the same supervisor enforcement path as other backends.
|
|
|
|
## Build Scripts
|
|
|
|
| Script | Platform | Purpose |
|
|
|---|---|---|
|
|
| `tasks/scripts/vm/build-libkrun.sh` | Linux | Builds libkrunfw and libkrun from source with the custom kernel config |
|
|
| `tasks/scripts/vm/build-libkrun-macos.sh` | macOS | Builds portable libkrunfw and libkrun from a prebuilt `kernel.c` |
|
|
| `tasks/scripts/vm/package-vm-runtime.sh` | Any | Packages `vm-runtime-<platform>.tar.zst` with libraries, gvproxy, umoci, and provenance |
|
|
| `tasks/scripts/vm/download-kernel-runtime.sh` | Any | Downloads runtime tarballs from the `vm-runtime` release and stages compressed files |
|
|
|
|
## Local Flow
|
|
|
|
```shell
|
|
# Download the current pre-built runtime and stage compressed artifacts
|
|
mise run vm:setup
|
|
|
|
# Build the bundled guest supervisor
|
|
mise run vm:supervisor
|
|
|
|
# Build the gateway and VM driver with embedded runtime artifacts
|
|
OPENSHELL_VM_RUNTIME_COMPRESSED_DIR=$PWD/target/vm-runtime-compressed \
|
|
cargo build -p openshell-server -p openshell-driver-vm
|
|
```
|
|
|
|
Use `FROM_SOURCE=1 mise run vm:setup` to build the runtime from source instead
|
|
of downloading `vm-runtime-<platform>.tar.zst`.
|
|
|
|
## CI Ownership
|
|
|
|
`release-vm-kernel.yml` is the on-demand producer for:
|
|
|
|
- `vm-runtime-linux-aarch64.tar.zst`
|
|
- `vm-runtime-linux-x86_64.tar.zst`
|
|
- `vm-runtime-darwin-aarch64.tar.zst`
|
|
|
|
Those artifacts stay on the rolling `vm-runtime` release. Normal `dev` and `v*`
|
|
release workflows download them, embed them into `openshell-driver-vm`, and
|
|
publish the driver binary next to `openshell-gateway`.
|
|
|
|
## Provenance
|
|
|
|
`package-vm-runtime.sh` writes `provenance.json` into each runtime tarball with
|
|
the platform, libkrunfw commit, kernel version, gvproxy and umoci versions,
|
|
GitHub SHA, and build time. The driver logs this metadata when it extracts and
|
|
loads a runtime bundle.
|
|
|
|
The release workflow also publishes GitHub artifact attestations for each
|
|
runtime tarball. Verify a downloaded runtime with:
|
|
|
|
```bash
|
|
gh attestation verify vm-runtime-linux-x86_64.tar.zst -R NVIDIA/OpenShell
|
|
```
|