Boot a VM image as a zone – Edera

Boot a VM image as a zone

Edera zones are normally composed from OCI images. A VM-image zone is a different zone type: it boots an unmodified, UEFI-bootable virtual machine disk image—raw or qcow2—directly, with no repackaging. This lets you run VM-based workloads, such as GPU fleet images or vendor appliances shipped as virtual machines, on Edera without converting them to containers.

⚠️
VM-image zones are an Early Access feature built on the KVM backend. They are not intended for production use and have not completed Edera’s security review.

Prerequisites

A KVM-backed Edera host. VM-image zones require the KVM virtualization backend, which is selected when you install Edera. They do not run on the Xen backend.
A UEFI-bootable disk image in raw or qcow2 format. The image boots through Edera’s UEFI firmware, so it must use UEFI boot rather than legacy BIOS.
A cloud-init-enabled image. Edera provisions the zone with a cloud-init seed that installs its in-zone agent. Without cloud-init the VM still boots, but the zone does not reach the ready state or support exec, logs, and metrics. The official Ubuntu cloud images work out of the box.
Familiarity with the protect CLI.

Stage the disk image

Copy the image into the daemon’s VM-image directory on the host, /var/lib/edera/protect/vm-images/:

sudo cp jammy-server-cloudimg-amd64.qcow2 /var/lib/edera/protect/vm-images/

The --vm-image flag takes the bare filename of an image in this directory—not a path. Keep the file extension consistent with the format.

Launch the zone

Launch a zone from the staged image with protect zone launch, passing both --vm-image and the required --vm-image-format:

# qcow2 image
protect zone launch \
  --name vm-demo \
  --vm-image jammy-server-cloudimg-amd64.qcow2 \
  --vm-image-format qcow2

For a raw disk image, set the format to raw:

# raw disk image
protect zone launch \
  --name vm-demo \
  --vm-image disk.raw \
  --vm-image-format raw

--vm-image-format is required. Edera does not detect the format automatically.

Verify the zone

Check that the zone reached the ready state:

protect zone list

Once ready, the zone behaves like any other Edera zone. Run a command inside it and read its console logs:

protect zone exec vm-demo hostname
protect zone logs vm-demo

Clean up

Destroy the zone when you’re done. This releases the lock on the image file so it can be reused:

protect zone destroy vm-demo

Requirements and limitations

VM-image zones are validated at launch. Keep these constraints in mind:

KVM backend only. VM-image zones require a host installed with the KVM backend. Launching one on a Xen host is rejected.
Explicit format is required. You must pass --vm-image-format raw or --vm-image-format qcow2. There is no automatic detection.
Filename, not a path.--vm-image takes a bare filename resolved against /var/lib/edera/protect/vm-images/. Values containing path separators are rejected.
Extension must match the format. A qcow2 image must have a .qcow2 extension. A raw image must not use .qcow2; raw images are typically .raw, .img, .disk, or have no extension.
No container payload.--vm-image is mutually exclusive with --kernel, --initrd, --addon, --create-scratch-disk, and --attach-scratch-disk. A VM image already carries its own kernel and root filesystem.
One live zone per image file. A given raw or qcow2 file can back only one running zone at a time. Launching a second zone from a file that is already in use fails with a lock error. Copy the image to a second filename to run two zones.
cloud-init is required for the full lifecycle. The zone reaches ready and supports exec, logs, and metrics only if the guest runs cloud-init to apply Edera’s provisioning seed.
Supported formats are raw and qcow2. No other disk image formats are supported.

Additional resources

Last updated on 2026-07-23