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 VMs with the same configuration and software. Each deployed VM can get its own guest identity (machine ID, SSH host keys, hostname, network bindings); see Deploying and guest identity.

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.
• Create a Template from a Copy of a VM: POST /api/v1/virtualization/computes/{id}/clone-to-template copies the VM's disks and registers the copy as a template, leaving the source VM as it is.
• Deploy from Template: POST /api/v1/virtualization/computes/from-template with template_id, name, destination storage_pool, and optionally guest_identity. Vapor makes a full copy of every template disk to provision the new VM, so deploying takes longer the larger the disks are, and the new VM does not depend on the template afterwards. Linked (copy-on-write) clones are not available.
• 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.

Deploying and Guest Identity

• Templates are exact copies. Converting a VM to a template, creating a template from a copy of a VM, and copying a template to another template never change the guest's identity. Vapor records the template source's network MAC addresses so that later deployments can update the guest's network configuration.
• Deploying offers the Guest identity choice. Like cloning, deploying from a template can reset the guest identity (Reset guest identity (recommended)) or keep an exact copy (Keep an exact copy). In the web UI, the deploy wizard shows the same Guest identity field as the Clone dialog. With guest_identity omitted, the host default applies. The 201 response includes the resolved guest_identity and an identity_reset result. What a reset changes, when it is not possible, and what the host needs are described in Guest Identity of a Clone.
• Templates created by copying a VM with an earlier Vapor version do not record the source's MAC addresses. When the template has one network interface, Vapor can still update the network configuration. With several interfaces, a reset may fail (or, with auto, complete with a warning) because the network configuration names MAC addresses Vapor does not know; create the template again from the original VM to fix this. Templates converted in place from a VM are not affected.