Boot-from-Volume Provisioning and Failure Recovery

Overview

Boot-from-volume lets you create a virtual machine whose root disk is a persistent block storage volume rather than an ephemeral disk. The volume persists after the VM is deleted, allowing the same root disk to be reused across VM lifetimes.

Boot-from-volume provisioning involves a coordinated sequence between the Compute Service and the Persistent Storage Service. Failures at any step can leave the VM in ERROR state or the boot volume in error or in-use state, sometimes with a partially created VM that you need to clean up.

In this guide, you will create a boot-from-volume VM, diagnose failures, and recover from partial creation.

Prerequisites

• A volume or image from which to boot.

• A volume type configured and working for standard volume creation.

• pcdctl configured and authenticated.

Create a VM from a Boot Volume

Option 1 — Create a New Boot Volume from an Image at Launch Time

This is the most common pattern. The Compute Service creates a new volume from the specified image and uses it as the VM's root disk.

pcdctl server create \
  --flavor <FLAVOR_NAME> \
  --image <IMAGE_UUID> \
  --boot-from-volume <SIZE_GB> \
  --volume-type <VOLUME_TYPE_NAME> \
  --network <NETWORK_UUID> \
  <VM_NAME>

Replace <SIZE_GB> with the desired boot volume size in gigabytes. The size must be at least as large as the image's minimum disk requirement.

Option 2 — Boot from an Existing Volume

If you already have a bootable volume (one created from an image or a previous boot-from-volume VM), launch directly from it:

pcdctl server create \
  --flavor <FLAVOR_NAME> \
  --volume <BOOT_VOLUME_UUID> \
  --network <NETWORK_UUID> \
  <VM_NAME>

Set the volume bootable flag

A volume must have its bootable property set to true before it can be used as a boot disk. Volumes created from images are automatically marked bootable. If you created a blank volume and populated it manually, mark it bootable:

pcdctl volume set --bootable <VOLUME_UUID>

Verify Successful Provisioning

After launching the VM, check that it reaches ACTIVE state and that the boot volume is in in-use state:

pcdctl server show <VM_UUID> -f value -c status
pcdctl volume show <BOOT_VOLUME_UUID> -f value -c status

Both should resolve within a few minutes. If either stays in a non-terminal state longer than five minutes, a failure has occurred.

Diagnose "Volume Provisioning Works but VM-from-Volume Fails"

A common failure pattern is: volumes create successfully and volumes attach to running VMs successfully, but launching a new VM with a boot volume fails.

Check Compute Service Logs

The Compute Service is the primary source of diagnostic information for VM launch failures. On the compute host where the VM was scheduled:

sudo grep <VM_UUID> /var/log/pf9/ostackhost.log | tail -100

Key error patterns:

Log Pattern	Meaning
No valid host was found	The Compute Service could not schedule the VM; typically a flavor or resource mismatch
Failed to attach volume	Volume attachment failed after the VM was created; storage connectivity issue
Timeout waiting for volume to attach	Volume attachment took too long; backend or network issue
Volume ... is not bootable	The volume does not have the bootable flag set
Volume ... is already in use	The volume is attached to another VM; cannot be used as a boot disk for a new VM
Image ... minimum disk size	The requested boot volume size is smaller than the image's minimum disk requirement

Check Persistent Storage Service Logs

Also review the storage service log for errors related to the boot volume UUID:

sudo grep <BOOT_VOLUME_UUID> /var/log/pf9/cindervolume-base.log | grep -E 'ERROR|WARN' | tail -50

Verify the Volume Type Is Correct

If the volume type used for the boot volume is misconfigured or points to a broken backend, volume creation will succeed but VM launch will fail because the volume cannot actually be provisioned on the backend.

pcdctl volume type show <VOLUME_TYPE_NAME>

Create a test volume of the same type to confirm the backend is healthy:

pcdctl volume create --type <VOLUME_TYPE_NAME> --size 1 test-boot-volume-check
pcdctl volume show test-boot-volume-check -f value -c status

If the test volume reaches available, the backend is healthy. Delete the test volume and continue diagnosing the VM-level failure.

Recover from Partial Creation

When a boot-from-volume VM fails partway through provisioning, you may be left with:

• A VM in ERROR state.

• A boot volume in error, in-use, or available state.

• Orphaned attachment records.

Follow these steps to clean up:

Step 1 — Delete the Failed VM

pcdctl server delete <VM_UUID>

If the VM is stuck in ERROR state and the standard delete fails, use the force-delete operation:

pcdctl server delete --force <VM_UUID>

Force delete and volume state

Force-deleting a VM does not always clean up the volume attachment. After force-deleting, check whether the boot volume is still in in-use state and clean up the attachment manually if needed.

Step 2 — Check and Reset the Boot Volume State

pcdctl volume show <BOOT_VOLUME_UUID> -f value -c status

If the volume is still in in-use or error state after the VM is deleted:

# List and delete orphaned attachments
pcdctl volume attachment list --volume-id <BOOT_VOLUME_UUID>
pcdctl volume attachment delete <ATTACHMENT_UUID>

# Reset volume state to available
pcdctl volume set --state available <BOOT_VOLUME_UUID>

Step 3 — Retry the VM Launch

Once the boot volume is in available state, retry the VM launch using option 2 (boot from existing volume):

pcdctl server create \
  --flavor <FLAVOR_NAME> \
  --volume <BOOT_VOLUME_UUID> \
  --network <NETWORK_UUID> \
  <VM_NAME>

If the launch fails again with the same error, address the root cause identified in the logs before retrying.

Considerations for Boot-from-Volume VMs

Volume Deletion on VM Deletion

By default, a boot volume created at launch time is not deleted when the VM is deleted. The volume persists in available state and can be reused. If you want the volume to be deleted automatically when the VM is deleted, set the delete_on_termination flag when creating the VM:

pcdctl server create \
  --flavor <FLAVOR_NAME> \
  --image <IMAGE_UUID> \
  --boot-from-volume <SIZE_GB> \
  --block-device source=image,dest=volume,size=<SIZE_GB>,shutdown=remove \
  --network <NETWORK_UUID> \
  <VM_NAME>

Snapshots of Boot-from-Volume VMs

When you take a snapshot of a VM whose root disk is a boot volume, the snapshot captures the boot volume. This is different from ephemeral-disk VM snapshots, which capture the ephemeral disk. Refer to Virtual Machine Snapshot for the full snapshot behavior comparison.

Live Migration of Boot-from-Volume VMs

VMs with boot volumes support live migration without additional configuration, as long as the boot volume's backend supports live migration. Refer to Storage Live Migration for prerequisites and limitations.

Next Steps

• Review Block Storage for how to configure volume backends and volume types.

• Review Volume State for a reference of all volume status values.

• For compute-side VM scheduling failures, see Failed to Deploy Virtual Machine.