Data volumes
Updated
A data volume is a disk with its own lifecycle. It is created on its own, attached to a machine, and outlives that machine when you delete it. Volumes are where anything you cannot afford to lose belongs.
Creating and attaching
Section titled “Creating and attaching”Create a volume from the Volumes page with Create volume. Give it a name, an optional purpose, and a size in GiB, and optionally attach it to a machine in the same step with Attach after creating. The host creates it already formatted as ext4 and empty. A row’s Attach and Detach buttons do the same later, and the list shows what each volume has written against its declared size.
What attaching does depends on the machine type, because the two are handed their disks differently.
- An AppVM is given a mount path. The volume is mounted there before the workload starts, and the directory is created if the image does not already have it.
- A classic VM is given a disk and nothing more. Its guest mounts it where you tell the guest to, so there is no mount path to supply, and the host refuses one.
Volumes can be attached read-only when the workload should not write to them. That is an AppVM option: a classic VM is handed a writable disk and its guest chooses its own mount options, so the host refuses a read-only request for one.
Attach and detach rules
Section titled “Attach and detach rules”The state a machine has to be in depends on which of the two it is.
| Classic VM | AppVM | |
|---|---|---|
| Attach | Created, powered off, or running | Powered off only |
| Detach | Created, powered off, or running | Powered off only |
A paused machine refuses both directions. Detaching is the one with a hard reason: pulling a disk needs the guest to answer, and a frozen guest cannot. A machine the host has marked failed is refused too, until it is stopped.
Attaching to a running classic VM hot-plugs the disk, which makes it visible to the guest immediately. The guest still has to mount it, the same as it would mount a disk it was given at boot.
A machine takes up to 25 data volumes. That is how far a guest’s disk naming goes before it stops being predictable, not a number picked for convenience.
From Free 1.3, on a host installed from a Virtainer image, each disk reports its own serial
to the guest: vt-root for the root disk, vt-data0, vt-data1 and so on for disks that
belong to the VM, and a serial derived from the volume id for a volume, which it keeps when
it moves to another machine. The disk then appears under /dev/disk/by-id/ as
virtio-<serial>. Existing VMs pick up the new serials at their next boot; if a guest uses
LVM, read LVM volume groups after upgrading to Free 1.3.
An externally managed host keeps the earlier behaviour, where every disk reports the same
serial.
Ownership
Section titled “Ownership”On an AppVM, mounting an untouched volume for the first time gives it the owner and permissions of the directory the image ships at that mount path. A volume that already holds files keeps its own ownership. A classic VM mounts its disk itself, so ownership is whatever the guest sets.
The volume’s contents are its own. Attaching a volume does not copy anything from the image into it.
Volumes and machine operations
Section titled “Volumes and machine operations”| Operation | Effect on volumes |
|---|---|
| Stop and boot | Kept, contents intact |
| Redeploy an AppVM | Kept, contents intact, while the system disk is reset |
| Delete the machine | Volumes are separate objects and are not deleted |
| Snapshot a classic VM | Each writable attached volume is captured inside its own disk file, and rolled back with the machine. See Snapshots |
Only volumes are this durable. The blank disks you add while creating a classic VM belong to that machine: they are partitioned and formatted by its guest, they are deleted with it, and they cannot be reattached somewhere else. Anything you would miss belongs on a volume you created and attached.
Deleting
Section titled “Deleting”Delete a volume from its row menu once nothing is attached to it. To remove several, tick their rows and delete them together: each is deleted in turn, and a volume that is still attached, or that a snapshot still needs, is left in place and named in the result rather than stopping the rest. The contents are gone for good.
Renaming and growing
Section titled “Renaming and growing”There is no volume detail page. Both actions live in the row menu on the Volumes list, under Rename / set purpose. Renaming opens Rename volume and changes the name and the purpose and nothing else. Machines already mounting the volume keep working, because they reference it by its id, and the id is deliberately not changeable: it is part of the file on disk and of every machine’s record, so a new id would be a different volume rather than a renamed one.
Growing opens Grow <name> and takes a New size (GiB); it can only go up. Asking for the size it already has does nothing, and asking for less is refused with “a volume can only grow”. There is no shrink, because there is no safe way to take space back from a filesystem a guest has written into.
A volume has to be detached before it can grow. While it is attached the menu item
is disabled and reads Grow — detach first, and the request is refused with
volume '<id>' is attached to <machine>; detach it before growing it. The disk
cannot change size under a guest that is using it: the guest would keep working
from the capacity it saw at boot.
Growing enlarges the disk, and the filesystem on it follows only where something resizes it. A volume is an ext4 filesystem written straight onto the disk, with no partition table. An AppVM resizes the filesystem for you: it runs an online resize each time it mounts the volume, so the extra space appears at the next boot (a volume mounted read-only is skipped). A classic VM’s guest owns the filesystem, so the extra space is not usable until you grow the ext4 filesystem inside the guest with your own tools, and it may need to be told the disk changed first. If you partitioned the disk yourself, the partition needs growing too. The host does not touch the contents of a classic VM’s disk.
A note on databases
Section titled “A note on databases”Database images often refuse to initialise into a directory that is not empty,
and a freshly formatted volume has a lost+found directory at its root. Mount
the volume on the parent directory and point the database’s data directory at a
subdirectory of it. See Will my image run?.