Boot a VM image as a zone

3 min read · Advanced

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.

Prerequisites

• A KVM-backed Edera host. VM-image zones require the KVM virtualization backend, which is selected when you install Edera. See Install Edera with KVM. 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. See Running Edera without Kubernetes.

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 (see Requirements and limitations).

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

• VM-image zones
• KVM architecture
• Running Edera without Kubernetes
• Edera CLI reference