Volume Snapshots and Backups
Overview
Volume Snapshots and Backups protect the data on a block storage volume with two related tools:
- Snapshot - A point-in-time mark on the volume's own storage backend. Created in seconds. Cheap because it only stores blocks that diverge from the original after the snapshot is taken. Good as a "safety net" before a risky change.
- Backup - A full copy of the volume written to a separate storage location (S3-compatible, NFS, or local disk). Slower and bigger than a snapshot, but it survives a complete loss of the source storage.
Both live on the same Snapshots & Backups tab on a volume's detail page in both the admin and user panels.
Concepts
- Volume - A piece of block storage that attaches to a virtual machine. See Block Storage.
- Storage backend - The actual disk system that holds the volume's bytes. Ceph (a distributed cluster) or qcow2 files on NFS or local disk.
- Point-in-time - Captures the volume's state at a specific moment. Reads taken later still see the volume as it was at that moment.
- Snapshot - A copy-on-write mark on the same backend the volume lives on. Cheap and fast. Only the blocks that change after the snapshot are stored separately.
- Backup - A full export of the volume to a separate storage destination. Survives loss of the source storage.
- Backup Storage - The remote destination the backup is written to (S3 bucket, NFS share, local mount). Configured per hypervisor by the admin, the same storage that powers instance backups.
- In-place restore - Overwrites the live volume with the snapshot or backup contents. Fast, but destroys whatever changed since the snapshot/backup.
- Restore to new volume - Creates a fresh volume from the snapshot or backup. Leaves the source volume alone. Safer.
- Active operation - The single snapshot, backup, or restore currently running on a volume. Only one is allowed at a time per volume.
- Cooldown - A short wait period after an operation finishes, before the next one can start on the same volume.
- qcow2 - A disk image file format used by QEMU. Used for the file-backed (non-Ceph) storage backend.
Snapshot vs. Backup at a Glance
| Snapshot | Backup | |
|---|---|---|
| Lives on | Same storage as the source volume | Separate Backup Storage (S3 / NFS / local) |
| Speed to create | Near-instant | Scales with volume size and network speed |
| Cost | Only the diverged blocks | Full volume size, every backup |
| Survives storage loss? | No | Yes |
| Restore in-place | Yes | Yes |
| Restore to new volume | Yes | Yes |
| Use case | Pre-change rollback insurance | Long-term retention, disaster recovery |
Volume snapshots and backups are full-only, there are no incremental chains. Every snapshot and every backup is self-contained.
Admin Setup
This feature has no dedicated admin page. It is configured through pieces you already manage elsewhere (volume plans and hypervisor backup storage). The customer-facing surface lives inside each volume's detail page.
Step 1: Confirm Backup Storage Exists
Each hypervisor that hosts volume storage needs a Backup Storage entry on its hypervisor group (the same setting that powers instance backups, see the Instance Backups guide). If a hypervisor has no backup storage, attempts to back up a volume on that hypervisor fail with "Hypervisor has no backup storage configured."
Snapshots do not need backup storage, they live on the source volume's own backend.
Step 2: Configure Volume Plans
The per-plan caps that control snapshot and backup behavior are on each Volume Plan. Open Block Storage then Plans in the admin sidebar (see Block Storage). For each plan, set:
- Max Snapshots - Hard cap on simultaneous retained snapshots (default 5).
- Max Backups - Hard cap on simultaneous retained backups (default 10).
- Snapshot Credit Value - Credits charged per GB / month for retained snapshots (default 0 = free within the cap).
- Backup Credit Value - Credits charged per GB / month for retained backups (default 0 = free within the cap).
Step 3: Roll Out the Slave Update
Each hypervisor needs a matching slave-agent update to handle the new volume snapshot and backup commands. Trigger the update from each hypervisor's manage page in the admin panel. The asynchronous update flow makes this safe to do live.
Step 4: Smoke-Test on a Non-Production Volume
- Take a snapshot.
- Create a backup.
- Restore-to-new-volume from each.
- Confirm the
volumes/{volume_id}/prefix appears in the backup destination and the new volume comes up healthy.
Where Customers See This Feature
Inside any volume's detail page (admin or user panel) there is a Snapshots & Backups tab. The tab has two sub-tabs (Snapshots and Backups), an active-operation banner, and a list of items with restore/delete buttons. Admins see this for any volume, users see it only for their own volumes.
Operations (User and Admin)
Take a Snapshot
- Open the volume's detail page.
- Open the Snapshots & Backups tab.
- Click Take Snapshot.
- Optional: give it a name. If you leave it blank a timestamped name is generated.
- Confirm. Status moves:
pending→creating→available.
The volume is briefly "busy" while the snapshot is being created. The active-operation banner at the top of the tab shows progress in real time.
Create a Backup
- Open the Snapshots & Backups tab.
- Open the Backups sub-tab.
- Click Create Backup.
- Optional: name the backup.
- Confirm. Status moves:
pending→availablewhen the export completes.
The export streams from the volume's storage backend to the Backup Storage configured for the volume's hypervisor (the same one used for instance backups). Volume backups are written under the path prefix volumes/{volume_id}/ inside that destination.
Restore - Roll Back This Volume (in-place)
- On the Snapshots or Backups sub-tab, click Restore on the row you want.
- Choose Roll back this volume.
- Type the volume's name to confirm.
- The volume is overwritten with the snapshot or backup contents.
In-place restore is blocked if the volume is attached to a running instance. Stop the instance or detach the volume first.
Restore to a New Volume
- Click Restore.
- Choose Restore to new volume.
- The dialog defaults to the source volume's plan and hypervisor group, both can be changed.
- Optional: name the new volume.
- Confirm. A fresh volume is created from the snapshot or backup. The source is untouched.
This is the safest option when you want to look at old data without touching the live volume.
Delete a Snapshot or Backup
- Click the trash icon next to the row.
- Type the snapshot or backup name to confirm.
- The item is removed (from storage for snapshots, from Backup Storage for backups).
Safety Controls
The platform enforces several guard rails so you cannot corrupt a volume or accidentally rack up costs.
One operation at a time, per volume
A volume can run only one snapshot, backup, or restore at a time. While an operation is in flight, the volume's active_operation field is set. A second request is rejected with a clear error ("Volume is busy with operation: snapshot"). Once the operation finishes, the field clears automatically.
Cooldown
After an operation finishes, a 5-minute cooldown applies before the next operation on the same volume. The UI shows a countdown. This stops accidental double-clicks and rate-limits API misuse.
Plan-level caps
Each volume plan defines:
- Max Snapshots (default 5)
- Max Backups (default 10)
When you hit the cap, new snapshots or backups are rejected with "Snapshot limit reached. Delete an existing snapshot first." Delete an item to free capacity.
Per-user in-flight limit
A single user can have at most three volume operations in flight across all their volumes at any moment. Prevents one busy customer from saturating the queue.
Live-volume protection
In-place restore is blocked when the volume is attached to a running instance. The UI shows a clear error and tells you what to do: stop the instance or detach the volume. Restore-to-new-volume has no such restriction.
Billing
Each volume plan has two billing fields specific to this feature:
| Field | What it means |
|---|---|
| Snapshot Credit Value | Credits per GB of retained snapshots, per month. |
| Backup Credit Value | Credits per GB of retained backups, per month. |
Both default to zero, meaning customers can take snapshots and backups within their plan caps for free. Set non-zero values to meter usage. Billing runs hourly inside the existing Cloud Service tick. Charges appear as line items in customer usage reports.
Only items in the available status are billed. Items in pending, creating, restoring, or failed status are not charged.
What's Not Yet Supported
This is the v1 release.
- Scheduled snapshots and backups - All operations are manual today. Scheduling will be added once usage patterns are clearer.
- Application-consistent snapshots via guest fsfreeze - A snapshot taken while a volume is attached to a running instance is crash-consistent (whatever was on disk at the moment), not application-consistent. For an application-consistent snapshot today, stop the instance or detach the volume first.
- Cross-storage-type restore - A backup taken from a Ceph volume can only be restored onto a Ceph-backed target, and a qcow2-file backup only onto a qcow2-file target. The restore dialog shows a clear error if you pick an incompatible target plan.
Troubleshooting
Snapshot or backup stuck in pending or started
A snapshot or backup that does not complete within 2 hours is marked failed automatically by the queue cleanup cron, and the volume's lock is released. Check the queue logs for the reason. Common causes: hypervisor offline, backup storage unreachable, source volume metadata corrupted.
"Volume is busy with operation: ..."
Another operation is running on the volume. Wait for it to finish (watch the active-operation banner). If a job looks truly stuck, the cleanup cron releases the lock within 2 hours, or an admin can mark the queue row failed in the database manually.
"Volume is in cooldown. Try again in N seconds."
The 5-minute cooldown is active. Wait for the countdown to reach zero.
"Backup limit reached" / "Snapshot limit reached"
The volume hit the plan's max_backups or max_snapshots cap. Delete an existing item to free capacity, or move the volume to a plan with a higher cap.
"Cannot restore in-place while attached to a running instance"
Stop the instance, or detach the volume from the instance, then retry. Or use Restore to new volume, which has no such restriction.
Backup created on Ceph cannot restore onto an NFS-backed plan
Cross-storage-type restore is not supported in v1. Pick a target plan whose storage type matches the source volume's storage type.
Related pages
- Block Storage - Create and manage the volumes this feature operates on.
- Instance Backups - Backups for whole virtual machines, uses the same Backup Storage targets.