Volumes and snapshots

A volume is a disk that outlives the machine attached to it, the host that machine ran on, and a wipe of that host's local disk. A machine's own disk is a cache. A volume is the truth.

Declaring one

A volume is part of an app's shape, so it belongs in the compose file rather than being created by hand beside it. The plan creates it before the service that mounts it.

services:
  postgres:
    image: postgres:17
    volumes:
      - pgdata:/var/lib/postgresql/data
    x-pilots:
      size_gib: 20
volumes:
  pgdata: {}

The top-level entry is the NAME and nothing else. The size is size_gib on the service that mounts it, because the service is what knows how much room its data needs, and it applies to every named volume that service declares. Left out, a volume is ten gibibytes.

The volume survives every redeploy of that service. The root filesystem does not: it is replaced by the next release, which is exactly why anything you need to keep goes on the volume and not in the image.

One replica, and why

A volume is mounted by one machine at a time. Two machines mounting one filesystem is two processes writing one filesystem, so a volume-backed service runs exactly ONE replica and asking for more is refused rather than quietly allowed.

A size change on such a service therefore holds requests for the moment between the old machine letting go and the new one mounting, rather than dropping them.

Snapshots

pilot volume ls
pilot volume snapshot pgdata
pilot volume snapshots pgdata
pilot volume restore pgdata 20260912T101500Z

A snapshot is a point-in-time copy. Restoring one puts it back as the volume's live disk, and a machine holding that volume cold-boots deliberately when it happens: its memory image describes the filesystem you just replaced, and waking it onto the restored disk would corrupt the new one within seconds.

pilot volume policy pgdata --cron @daily --keep-daily 7 --keep-weekly 4

Two retention numbers because they answer different questions. Daily retention is how far back you can go at a day's resolution, and weekly retention keeps the newest snapshot of each recent week, which reaches much further back for very little space. Both left at zero keeps everything, so a schedule with no retention grows without bound.

What deletes what

A filesystem check runs before any guest is given a volume, because a host that died mid-write leaves an image that still believes it is clean.

When it is refused

• volume_in_use means something else holds it. The answer names what: destroy that machine, or detach it from that service.
• bad_request about replicas means a volume-backed service was asked for more than one. Drop the replicas, or drop the volume.