Durable block storage that outlives the VM it is attached to
A guest's root disk dies with the VM. A volume is where state survives past
DELETE /vms/{id} — a checked-out repo, a database, a build cache.
POST /api/v1/volume-claims {"host_id": "...", "name": "...", "size_gb": ...}
Choose the host where the data will live. Creation commits the requested size on that host and asks its agent to create a sparse raw disk, without creating a VM. Sparse disks consume physical space as data is written; creation does not preallocate every block or format a filesystem.
Wait for status available before attaching the volume. provisioning means
the agent has not yet confirmed that the disk exists. An unavailable host cannot
confirm the disk's presence.
Name the claim on POST /api/v1/vms:
POST /api/v1/vms {"volume_claims": ["<name or id>", ...]}
The volume must be available on the VM's selected host. A volume can be held by one VM at a time; attaching it on another host is refused with 409. VM creation does not provision unbound claims.
Devices come in a fixed order: root is /dev/vda, the cloud-init seed is
/dev/vdb, the first volume is /dev/vdc, then the rest in the order named.
A volume is a raw block device. The guest partitions, formats and mounts it — eitri never touches the bytes:
sudo mkfs.ext4 /dev/vdc && sudo mount /dev/vdc /mnt
Deleting the VM frees the claim once the VM is reaped; the data stays, the
volume returns to available when its host confirms its presence, and the next
VM naming the claim sees it.
GET /api/v1/volume-claims
Shows each claim's status, host_id, vm_id and present.
DELETE /api/v1/volume-claims/{id}
Deletes the claim and its data. Refused with 409 while a VM holds it. Size is fixed once a claim is provisioned. Disk capacity remains committed until the host confirms deletion of the backing file.
A host cannot be removed while it holds volumes — delete their claims first. Force-removing a host discards its volume placements and returns their claims to an unbound state. Those claims cannot be attached; delete them and create new volumes on another host.
Volumes need an agent at or above v0.0.8-pre.1. An older agent's host
refuses a volume-bearing create with an upgrade link.
The fleet console's Volumes section lists each claim's name, ID, size, status, selected host, holder VM and presence. Create volumes with a host, name and size, and delete an unheld claim after confirming that its data will be destroyed. Held claims stay visible but cannot be deleted.
The Create VM form keeps volume selection in click order and sends that order to the API. Only available volumes on the selected host can be added. Claims held by a VM or placed on another host remain selected and removable when the host changes; the form explains the incompatibility and requires clearing it before submission. The VM page lists its attached claims; this list does not indicate guest device order.