docs/volumes.md

Ref: Size: 1.7 KiB History
# Volumes

*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.

## Claim storage

    POST /api/v1/volume-claims {"name": "...", "size_gb": ...}

Returns a claim, status `pending`.

## Attach at create

Name the claim on `POST /api/v1/vms`:

    POST /api/v1/vms {"volume_claims": ["<name or id>", ...]}

The first VM naming a pending claim binds it to that VM's host. Every later
VM using the same claim must be placed on that host — naming a different one
is refused with 409.

## In the guest

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:

```sh
sudo mkfs.ext4 /dev/vdc && sudo mount /dev/vdc /mnt
```

## Lifecycle

Deleting the VM frees the claim once the VM is reaped; the data stays, 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 bound.

## Hosts

A host cannot be removed while it holds volumes — delete their claims first.
Force-removing a host destroys its volumes and returns their claims to
pending.

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.

## Related

- [quickstart](quickstart.md)
- [networking](networking.md)