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, then attach it to a machine at a mount path. The host formats it and mounts it into the machine at that path, creating the directory if the image does not already have it.

Volumes can be attached read-only when the workload should not write to them.

Attach and detach rules

Operation	When
Attach	While the machine is running, or before it starts
Detach	Only while the machine is stopped

Why detach is offline only

The volume is mounted inside the workload for as long as the machine runs. Pulling it out from underneath a running workload would break its data path with no chance to unmount cleanly, so Virtainer Lite does not offer it.

Ownership

The first time a new volume is attached, it takes its owner and permissions from the directory the image ships at that mount path.

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	Not allowed while a volume is attached. See Snapshots

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