Snapshot Resource Kind

Kind: SnapshotapiVersion: pivirt.hu/v1Aliases: snap, snaps

The Snapshot resource declares a point-in-time checkpoint of a virtual machine’s disks and runtime memory state. When applied to a running virtual machine, pivirtd issues guest filesystem freeze (guest-fsfreeze-freeze) via the QEMU Guest Agent and executes QMP savevm to guarantee crash-consistent or application-consistent snapshots.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: Snapshot, snapshot, snapshots, snap, snaps.

---

Example Manifests

Pre-Maintenance Checkpoint

apiVersion: pivirt.hu/v1
kind: Snapshot
metadata:
  name: pre-upgrade-backup
  labels:
    scope: maintenance
spec:
  vmName: web-01
  description: "Snapshot taken prior to kernel and application upgrade"

Application Checkpoint

apiVersion: pivirt.hu/v1
kind: Snapshot
metadata:
  name: clean-state-v1
spec:
  vmName: db-01
  description: "Baseline state after initial schema migration"

---

Specification Reference (spec)

Field	Type	Required	Default	Description
vmName	string	Yes		Target virtual machine name
description	string	No	""	Human-readable note explaining the snapshot purpose

---

Snapshot Lifecycle & Mechanics

1. Guest Filesystem Quiescing:
   • If the guest runs the QEMU Guest Agent, pivirtd freezes guest filesystems before committing the snapshot.
   • If the guest agent is absent or times out, the snapshot proceeds in crash-consistent mode.
2. QMP Execution:
   • For stopped VMs: records disk metadata.
   • For running VMs: commits disk copy-on-write delta and captures RAM memory state.
3. Owner References:
   • Snapshots can specify ownerReferences pointing to their parent VirtualMachine. With blockOwnerDeletion: true, the VM cannot be deleted while a critical snapshot exists.

---

CLI Management Examples

# Apply a snapshot manifest (takes snapshot immediately)
pivirtctl apply -f snapshot.yaml

# List all snapshots for the host
pivirtctl get snapshots

# List using short alias
pivirtctl get snaps

# Inspect snapshot metadata
pivirtctl describe snapshot pre-upgrade-backup

# Delete a snapshot (safely releases COW delta images)
pivirtctl delete snapshot pre-upgrade-backup