Hotswap Disk Attachments

Hotswap Disk Attachments allow you to attach and detach disks from a running VM without stopping it. This is useful when you need to dynamically add or remove storage from a VM, for example when using Kubernetes persistent volumes via a CSI driver, or when you need to temporarily attach a disk to transfer data.

How hotswap attachments differ from permanent disks

VMs have two ways to attach disks:

  • Permanent disks are specified when the VM is created, or added during a stopped state, and remain attached through VM restarts. To change a permanent disk, you first need to stop the VM.
  • Hotswap attachments can be created and deleted while the VM is running. The disk attaches or detaches immediately without interrupting the VM. Hotswap attachments persist across VM restarts; the disk is automatically reattached when the VM starts.

Both methods begin with creating a disk. Permanent disks are referenced directly in the VM's configuration. Hotswap attachments are separate resources that reference both a disk and a VM, so neither the disk nor VM configuration needs to be modified directly. This separation allows different users or automated systems (such as a CSI driver) to manage disk attachments independently from VM management.

How hotswap attachments work

A Hotswap Disk Attachment is a resource that links a disk to a VM. When you create an attachment:

  1. The attachment references both the target VM and the disk to attach
  2. The system validates that the disk exists and isn't already attached elsewhere
  3. The disk is attached to the running VM using the SCSI bus
  4. The attachment status is updated to reflect whether the operation succeeded

The disk appears as a new block device inside the VM. When you delete the attachment, the disk is detached from the VM and becomes available for use elsewhere.

Technical details

Hotswap disks use the SCSI bus rather than the virtio bus used by permanent disks. The SCSI bus supports hot swapping while providing performance comparable to virtio; you shouldn't see any significant difference in disk I/O between hotswap and permanent attachments. Each VM can have up to 255 hotswap disk attachments.

Identifying disks inside the VM

Each hotswap disk attachment is assigned a serial number, which is reported in the attachment status. You can use this serial to reliably identify the corresponding block device inside the VM, which is particularly useful when multiple disks are attached.

The disk is available at:

/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_<SERIAL>

For example, if the attachment status reports a serial of hs-my-data-disk, the device path would be /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_hs-my-data-disk.

Attachment status

Each hotswap attachment tracks its state through status conditions:

  • Ready - The disk is successfully attached to the VM
  • Not Ready - The attachment failed. For example, the referenced disk or VM doesn't exist, or the disk is already attached elsewhere.

The disk and VM resources also reflect hotswap attachment status, allowing you to see which disks are attached to which VMs from either resource.

Use cases

Common use cases for hotswap disk attachments include:

  • Kubernetes persistent volumes - The evroc CSI Driver uses hotswap attachments to dynamically provision storage for containers running on evroc VMs
  • Data migration - Temporarily attach a disk to copy data, then detach and attach it to another VM
  • Dynamic scaling - Add storage to a running application without downtime
  • Backup and recovery - Attach disks containing backup data to restore a system

Constraints

  • A disk can only be attached to one VM at a time (whether permanent or hotswap)
  • A disk can't be both permanently attached and hotswap-attached to the same VM
  • The disk and VM must be in the same zone
  • Disks attached via hotswap can't be deleted until the attachment is removed

Next steps