feat(base-images): add managed base image bundles with cache retention, hosted manifests, and opt-in integration boot testing

2026-05-01 13:30:51 +00:00
parent 0ace928886
commit 9d0a57c5de
19 changed files with 2015 additions and 148 deletions
@@ -0,0 +1,34 @@
+# SmartVM Base Image Bundles
+
+This directory documents the project-owned base image manifest format. The actual kernel and rootfs binaries should be hosted as release assets or in object storage, not committed to git.
+
+## Bundle Layout
+
+A hosted bundle should expose three files:
+
+```text
+smartvm-minimal-v1-x86_64.manifest.json
+vmlinux
+rootfs.ext4
+```
+
+The manifest is the only file shape `smartvm` needs to know. It points at the hosted kernel and rootfs artifacts and records checksums.
+
+## Manifest Fields
+
+- `schemaVersion`: currently `1`
+- `bundleId`: stable cache key, using letters, numbers, dot, underscore, and dash only
+- `arch`: `x86_64` or `aarch64`
+- `firecrackerVersion`: Firecracker version validated with this bundle
+- `rootfsType`: `ext4` or `squashfs`
+- `rootfsIsReadOnly`: use `true` for squashfs or immutable rootfs images
+- `bootArgs`: kernel boot args to use with the bundle
+- `kernel`: hosted kernel artifact URL/path plus `sha256` for URL artifacts and optional `sizeBytes`
+- `rootfs`: hosted rootfs artifact URL/path plus `sha256` for URL artifacts and optional `sizeBytes`
+- `fileName`: optional plain output filename; path separators are rejected
+
+`sha256` is required for hosted URL artifacts. `sizeBytes` is optional but helps catch incomplete downloads.
+
+## Cache Behavior
+
+Downloaded bundles are cached under `/tmp/.smartvm/base-images` by default. The cache keeps two bundles unless `maxStoredBaseImages` is configured. Eviction is announced with `console.warn`.