> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/storage/troubleshooting-and-log-files/boot-from-volume-troubleshooting.md). # 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. ```bash pcdctl server create \ --flavor \ --image \ --boot-from-volume \ --volume-type \ --network \ ``` Replace `` 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: ```bash pcdctl server create \ --flavor \ --volume \ --network \ ``` {% hint style="info" %} **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: ```bash pcdctl volume set --bootable ``` {% endhint %} ### Verify Successful Provisioning After launching the VM, check that it reaches `ACTIVE` state and that the boot volume is in `in-use` state: ```bash pcdctl server show -f value -c status pcdctl volume show -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: ```bash sudo grep /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: ```bash sudo grep /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. ```bash pcdctl volume type show ``` Create a test volume of the same type to confirm the backend is healthy: ```bash pcdctl volume create --type --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 ```bash pcdctl server delete ``` If the VM is stuck in `ERROR` state and the standard delete fails, use the force-delete operation: ```bash pcdctl server delete --force ``` {% hint style="warning" %} **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. {% endhint %} ### Step 2 — Check and Reset the Boot Volume State ```bash pcdctl volume show -f value -c status ``` If the volume is still in `in-use` or `error` state after the VM is deleted: ```bash # List and delete orphaned attachments pcdctl volume attachment list --volume-id pcdctl volume attachment delete # Reset volume state to available pcdctl volume set --state available ``` ### 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): ```bash pcdctl server create \ --flavor \ --volume \ --network \ ``` 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: ```bash pcdctl server create \ --flavor \ --image \ --boot-from-volume \ --block-device source=image,dest=volume,size=,shutdown=remove \ --network \ ``` ### 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](/private-cloud-director/virtualized-clusters/virtualmachine/virtual-machine-snapshot.md) 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](/private-cloud-director/storage/storage-live-migration.md) for prerequisites and limitations. ## Next Steps * Review [Block Storage](/private-cloud-director/storage/block-storage.md) for how to configure volume backends and volume types. * Review [Volume State](/private-cloud-director/storage/volume/volume-state.md) for a reference of all volume status values. * For compute-side VM scheduling failures, see [Failed to Deploy Virtual Machine](/private-cloud-director/virtualized-clusters/troubleshooting-and-log-files/failed-to-deploy-virtual-machine.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.platform9.com/private-cloud-director/storage/troubleshooting-and-log-files/boot-from-volume-troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.