Data volumes

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

Create a volume from the Volumes page with a size. The host creates it already formatted and empty.

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.

Read-only holds at every layer

A read-only volume is read-only in more than the guest’s mount option. The storage daemon serves the disk read-only, and the machine’s own process is never given write access to it, so a workload running as root inside the machine still cannot write.

Read-only does not make a volume shareable. A volume is still attached to at most one machine at a time, and attaching it to a second one is refused until the first detaches it.

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.

Detaching from a running classic VM is a surprise removal

The disk disappears from the running guest immediately. Unmount it inside the guest first, or unsaved data on it is lost. The disks after it are renumbered down one letter at the next boot, since a disk’s letter is its position in the machine’s disk list. Mount by UUID rather than by device name.

Why an AppVM is stopped-only

The volume is mounted for the workload at boot and held there for as long as the machine runs. There is no step that unmounts it first, and the platform has no way to ask the workload to release it, so a live detach would always pull data out from under the workload. Virtainer Free does not offer it.

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.

Non-root workloads and new mount points

If the image does not contain the directory, the mount point is created owned by root, and a workload running as a non-root user will not be able to write to its own volume.

Either use an image that ships the directory with the right owner, or use an image whose entrypoint starts as root and fixes ownership itself. Docker behaves the same way.

The volume’s contents are its own. Attaching a volume does not copy anything from the image into it.

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	Captured inside the volume’s own disk file, and rolled back with it. 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.

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 nothing else. The partition table and the filesystem inside it keep their old size, so the extra space is not usable until you grow them your own tools inside the guest. A Linux guest normally needs a partition resize and then a filesystem resize, and it may need to be told the disk changed before either runs. The host deliberately stops at the disk: it has no way to know what filesystem you put in there, and guessing is how data gets destroyed.

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