Skip to content

v0.3.0-alpha.2 — Pluggable storage + vendor-agnostic iSCSI

Pre-release
Pre-release

Choose a tag to compare

View all tags
@github-actions github-actions released this 09 May 08:37
· 71 commits to main since this release
v0.3.0-alpha.2
f864231

v0.3.0-alpha.2 — Pluggable storage, vendor-agnostic iSCSI

This is the storage release. Backends are now mix-and-match from a single Add Backend UI, and the new iscsi_lvm backend turns any iSCSI target into a vendor-agnostic per-VM block-device pool — Proxmox-equivalent, no per-vendor REST adapter required.

Status: Alpha. Verified end-to-end via a 23-assertion integration suite running inside a fresh KubeVirt VM against a live LIO iSCSI target. See infra/test/HANDOFF.md.

Highlights

iscsi_lvm storage backend

Vendor-agnostic auto-provisioning of per-VM block devices on top of any iSCSI target. Mirrors Proxmox VE's LVM-on-iSCSI mode:

  1. Operator carves one big LUN on any iSCSI array (TrueNAS, Pure, Synology, plain Linux LIO, …).
  2. Click Add Backend → iSCSI + LVM in the UI, fill portal + IQN + VG name.
  3. Click Initialize Volume Group → type-to-confirm dialog → agent runs pvcreate + vgcreate once.
  4. Every subsequent VM-create allocates its own lvcreate slice. lvchange -aey exclusive activation gates per-VM access — safe foundation for live migration when you go multi-host.

No per-vendor adapters. No REST keys. Add a SAN to the UI and N VMs auto-provision their own disks on it.

NFS auto-mount via the agent

Manager runs unprivileged. The agent (which has root) handles mount.nfs over /v1/storage/nfs/*. Operators don't SSH the host to mount NFS exports — they fill the form, click Add, the manager probes and reports success/failure right there.

Live registry — no manager restart

Add or delete a backend through the UI and it's immediately usable for VM-create. The previous behavior (TOML-only registry, restart required) is gone. UI-sourced backends are tracked separately (storage_backend.source = 'ui') so the startup TOML reconciler doesn't sweep them away.

Tiered backend kind dropdown

Three recommended kinds shown by default in Add Backend: local_file, nfs, iscsi_lvm. Vendor-specific or operationally heavyweight kinds (iscsi generic, truenas_iscsi, spdk_lvol) tucked behind a Show advanced kinds disclosure. Default selection is local_file (zero-deps).

Platform auto-update

Settings → Updates lets admins upload .nqupdate bundles or enable internet checks against a manifest URL. Apply order is manager → agents (rolling) → UI; running VMs are not disturbed by agent restart. Binaries land at /opt/nqrust/bin/<name>.<version> with a <name> symlink for atomic swap.

What changed since v0.2.3

Added

  • Storage backends: iscsi_lvm, nfs (auto-mount), platform auto-update.
  • ControlPlaneBackend trait gains probe(), host_path_for(), activate_volume(), deactivate_volume() (default no-ops; iscsi_lvm overrides).
  • POST /v1/storage_backends/:id/initialize with destructive-confirmation flow.
  • Migration 0037_storage_backend_source.sql + 0038_iscsi_lvm_backend.sql.
  • VM lifecycle hooks: activate_volume before Firecracker spawn, deactivate_volume after stop.
  • Host package dependencies expanded — installer + air-gapped bundle now ship open-iscsi, lvm2, qemu-utils, nfs-common. iscsid enabled automatically post-install.
  • infra/test/iscsi-alpha-{vm.yaml,install.sh,runner.sh,HANDOFF.md} — full KubeVirt-based integration suite (23/23 passing on this release).

Fixed (alpha.2 vs alpha.1)

  • ensure_volume_registered was failing on block-device rootfs paths (fs::metadata returns 0, violated positive_size); deactivate hooks never fired on stop. Volume attachment now goes through provision_rootfs's structured handle (98c99a6).
  • restart_vm rejected /dev/<vg>/<lv> paths because ensure_allowed_path only permitted MANAGER_IMAGE_ROOT / MANAGER_STORAGE_ROOT. Backend-resolved device paths now bypass it (49eb4a7).

Changed

  • Manager + agent installed under /opt/nqrust/bin/<name>.<version> with symlink (auto-update layout).
  • systemd units set RestartForceExitStatus=42 so a clean self-update exit triggers restart on the new binary.

Install

The release ships software artifacts only — kernel + rootfs come from v0.2.3 (the install script handles fallback transparently):

# Online install (recommended)
curl -fsSL https://github.com/NexusQuantum/NQRust-MicroVM/releases/latest/download/install.sh | sudo bash

Or use the test harness directly (in a fresh KubeVirt / cloud-init VM):

curl -fsSL https://raw.githubusercontent.com/NexusQuantum/NQRust-MicroVM/main/infra/test/iscsi-alpha-install.sh | VERSION=v0.3.0-alpha.2 sudo bash

Test result

T1 Backend create + duplicate-name        ✅ 2/2
T2 Validation rejects missing fields      ✅ 3/3
T3 Initialize VG + idempotent + verified  ✅ 6/6
T4 Wrong-kind initialize → 409            ✅ 1/1
T5 VM lifecycle on iscsi_lvm              ✅ 8/8
T6 Live registry + volume protection      ✅ 3/3
                                            23/23 against released musl artifact

Detailed walkthrough: docs/runbooks/iscsi-lvm-troubleshooting.md · infra/test/HANDOFF.md

Known caveats

  • Single-host data plane only: clone_from_image writes the initial rootfs from the manager's local /srv/images. For genuine multi-host clusters the agent on a different machine wouldn't see the manager's local image; track for the multi-host data-plane delegation follow-up.
  • No image artifacts in this release: kernel + rootfs unchanged since v0.2.3, install scripts pull them from there. Fresh stable will reship them.
Assets 10
Loading