Snapshots & Templates

Vapor provides mechanisms to capture point-in-time states of virtual machines for testing, backups, or rapid instance replication.

---

VM Snapshots

A snapshot records the state of a virtual machine's disk images and optionally its active memory (RAM) at a specific moment.

Snapshot Capabilities and Memory State

Different storage backends and guest configurations support different snapshot features:

• Capabilities Check: Before taking a snapshot, Vapor queries GET /api/v1/virtualization/computes/{id}/snapshots/capabilities to determine if memory-inclusive snapshots (supports_memory) are supported.
• Include Memory: If supported, you can check Include Memory during creation to save the active RAM state. This allows the VM to resume execution from the exact point it was snapshotted, preserving running processes. If memory is not saved, reverting to the snapshot will boot the VM into a powered-off state.
• Filesystem Quiescing: When quiescing is enabled (quiesce: true), Vapor uses the QEMU Guest Agent to pause in-guest filesystem I/O operations and flush dirty cache blocks to disk before capturing the snapshot.
• External Snapshots: Under certain storage layouts, external snapshots (force_external: true) can be forced to create overlay files rather than modifying internal QCOW2 structures.

Management Operations (API & UI)

• List Snapshots: GET /api/v1/virtualization/computes/{id}/snapshots
• Create Snapshot: POST /api/v1/virtualization/computes/{id}/snapshots with parameters: name, description, include_memory (bool), quiesce (bool), force_external (bool).
• Get Snapshot Detail: GET /api/v1/virtualization/computes/{id}/snapshots/{snapshot_name}
• Revert to Snapshot: POST /api/v1/virtualization/computes/{id}/snapshots/{snapshot_name}/revert
• Delete Snapshot: DELETE /api/v1/virtualization/computes/{id}/snapshots/{snapshot_name}

WARNING

Snapshots are dependent on the underlying virtual disk file chain. If the base virtual disk image is deleted or corrupted, the snapshots will be unrecoverable. Snapshots should not be treated as standalone backups.

---

VM Templates

Templates allow administrators to freeze a virtual machine configuration as a read-only master image (golden image) to deploy new, identical VMs.

Template Lifecycle and Conversion

• Convert VM to Template: POST /api/v1/virtualization/computes/{id}/convert-to-template with description. The VM must be powered off. Once converted, the VM is removed from the active computes list (GET /virtualization/computes) and isolated in the templates registry (GET /virtualization/computes/templates).
• Start Block: Templates cannot be powered on or executed directly. Attempting to start a template will return an HTTP 409 Conflict error.
• Deploy from Template: POST /api/v1/virtualization/computes/from-template with template_id, name, and destination storage_pool. Vapor performs a fast copy-on-write clone of the template's disk volumes to provision a new VM.
• Convert Template back to VM: POST /api/v1/virtualization/computes/templates/{template_id}/convert-to-vm. This registers the template back as a standard, bootable VM.
• Delete Template: DELETE /api/v1/virtualization/computes/templates/{template_id}?remove_disks=true prunes the template and optionally purges its backing storage disks.