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`.
@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "bundleId": "smartvm-minimal-v1-x86_64",
+  "name": "SmartVM minimal x86_64 bundle",
+  "arch": "x86_64",
+  "firecrackerVersion": "v1.15.1",
+  "rootfsType": "ext4",
+  "rootfsIsReadOnly": false,
+  "bootArgs": "console=ttyS0 reboot=k panic=1 pci=off",
+  "kernel": {
+    "url": "https://assets.example.com/push.rocks/smartvm/base-images/smartvm-minimal-v1/x86_64/vmlinux",
+    "fileName": "vmlinux",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "sizeBytes": 12345678
+  },
+  "rootfs": {
+    "url": "https://assets.example.com/push.rocks/smartvm/base-images/smartvm-minimal-v1/x86_64/rootfs.ext4",
+    "fileName": "rootfs.ext4",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "sizeBytes": 12345678
+  }
+}