docs: guides for backing up and restoring KubeVirt VirtualMachines

[anisurrahman75]

Adds a guides/kubevirt section documenting backup and restore of a KubeVirt VirtualMachine, following the layout and writing conventions of guides/workloads.

Pages

Page	Menu entry
guides/kubevirt/overview/index.md	How Backup and Restore works?
guides/kubevirt/virtualmachine/index.md	Backup & Restore a VirtualMachine

guides/kubevirt sits at weight 25, between Workload's Volumes (20) and Stand-alone Volumes (30). Identifiers are kubevirt, kubevirt-overview and kubevirt-virtualmachine; none collide with existing docs.

Seven runnable manifests under virtualmachine/examples/: the VM and its dependencies, BackupStorage, RetentionPolicy, BackupConfiguration, RestoreSession, and a pair of Jobs that seed and verify sample data on the disks.

What the overview covers

• What gets backed up — a VirtualMachine is a graph, not one object: the VM, its DataVolumes and PVCs, cloud-init and access-credential Secrets, ConfigMaps, ServiceAccounts, instancetype/preference ControllerRevisions, TPM/EFI backend and memory-dump PVCs. Runtime objects (VMI, virt-launcher) are deliberately excluded, so a restored VM cold-boots.
• The Snapshot layout — one manifest component plus one volume-<pvc-name> per disk, which is what makes single-disk and manifest-only restores possible.
• Stopped vs running — chosen automatically from the VM's state. A running VM is backed up through a VirtualMachineSnapshot, so KubeVirt owns the guest freeze; consistency depends on qemu-guest-agent, and crash-consistent still succeeds with a warning. The CSI snapshot / default VolumeSnapshotClass / Snapshot feature gate prerequisites apply only to running VMs.
• Numbered backup and restore step lists, in the same style as the workloads overview.
• A flow diagram for each process, embedded in the same <figure> markup the sibling overviews use.

What the step-by-step guide covers

A full cycle on a stopped VM: create the VM and its dependencies, seed sample data and note its checksums, configure the backend, back up, verify the Snapshot components, delete the whole VM stack, restore, and confirm the checksums match.

Two things specific to VirtualMachines are called out where a reader would otherwise get stuck:

• A RestoreSession must not set spec.target. The VM does not exist yet at restore time, so a target pointing at a missing object is never found.
• Disks are restored before the manifests are applied, which is why the restored DataVolumes come back already Succeeded — CDI adopts the populated PVCs rather than re-importing them.

The guide uses the single logical-backup / logical-restore tasks, and notes that the granular manifest-backup / volume-backup pair is available for anyone who wants the two halves as separate task containers.

About the diagrams

The existing overview diagrams are 960x540 Google Slides exports with their text flattened to vector paths, which is why they weigh ~250 KB each. There is no source file in the repo to extend, so these two are authored directly as SVG at the same viewBox, using real <text> elements: ~9 KB each, searchable, and editable in a text editor. Both were rendered and checked visually.

Notes for review

• Command outputs are taken from a real run on a k3s cluster with KubeVirt v1.8.4 and CDI v1.65.0, with object names changed to the guide's naming.
• The running-VM section describes the behavior and prerequisites without a full walkthrough, since the walkthrough here is the stopped-VM path.

Related: kubestash/kubevirt#1 (the addon), kubestash/kubestash#386 and kubestash/installer#365 (the operator and RBAC changes it needs).

[github-actions]

Visit the preview URL for this PR (updated for commit da13eb4):

https://kubestash-qa--pr101-kubevirt-l3jzt8zp.web.app

_{(expires Mon, 07 Sep 2026 09:15:43 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 7765752f86b485f0f549c1d5d58c61af5e2ecd74}