photoncloud-monorepo/docs/ops/qcow2-artifact-plan.md

PlasmaVMC qcow artifact plan (for integration gate e2e)

• Goal: provide a reproducible qcow2 image + env wiring so plasmavmc e2e (QEMU-backed) can run in the integration matrix without manual prep.
• Constraints: small (<150MB), no network during gate run, works under nix develop; use virtio drivers; avoid licensing issues.

Candidate image

• Alpine cloud image (latest stable) is small and permissively licensed; includes virtio modules.
• Fallback: Build a 1G qcow2 via qemu-img create -f qcow2 plasma-mini.qcow2 1G + virt-make-fs on a tiny rootfs (busybox/alpine base).

Provisioning steps (once, cacheable)

1. In nix shell (has qemu-img): qemu-img convert -f qcow2 -O qcow2 alpine-cloudimg-amd64.qcow2 plasma-mini.qcow2 or qemu-img create -f qcow2 plasma-mini.qcow2 1G.
2. Inject default user+ssh key (optional) via cloud-init seed ISO or virt-make-fs (avoid during gate).
3. Store artifact under .cccc/work/artifacts/plasma-mini.qcow2 (or cache bucket if available).
4. Record SHA256 to detect drift.

Gate wiring

• Env vars: PLASMAVMC_QEMU_PATH (e.g., /run/current-system/sw/bin/qemu-system-x86_64 in nix shell), PLASMAVMC_QCOW2_PATH (absolute path to plasma-mini.qcow2).
• Update scripts/integration-matrix.sh docs to mention envs; optionally add just integration-matrix [--skip-plasma] wrapper that injects defaults when present.

Time/budget

• Download + convert: ~2-3 minutes once; gate runs reuse artifact (no network).
• If artifact absent, plasmavmc e2e remain ignored; matrix still green on unit/integration subsets.

Open questions

• Where to store the qcow2 artifact for CI (git LFS? remote cache?) to avoid repo bloat.
• Is cloud-init desirable for tests (SSH into VM) or is raw boot enough for current e2e?