Merge pull request #87808 from jherrman/CNV-37032

OSDOCS#37032: Updates to snapshot docs in CNV

Author: xenolinux

modules/virt-about-vm-snapshots.adoc

@@ -18,7 +18,13 @@ The snapshot stores a copy of each Container Storage Interface (CSI) volume atta
 You can perform the following snapshot actions:
 
 * Create a new snapshot
-* Create a copy of a virtual machine from a snapshot
+* Create a clone of a virtual machine from a snapshot
++
+[IMPORTANT]
+====
+Cloning a VM with a vTPM device attached to it or creating a new VM from its snapshot is not supported.
+====
+
 * List all snapshots attached to a specific VM
 * Restore a VM from a snapshot
 * Delete an existing VM snapshot

modules/virt-creating-vm-snapshot-cli.adoc

@@ -10,7 +10,27 @@ You can create a virtual machine (VM) snapshot for an offline or online VM by cr
 
 .Prerequisites
 
-* Ensure that the persistent volume claims (PVCs) are in a storage class that supports Container Storage Interface (CSI) volume snapshots.
+* Ensure the `Snapshot` feature gate is enabled for the `kubevirt` CR by using the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc get kubevirt kubevirt-hyperconverged -n {CNVNamespace} -o yaml
+----
++
+.Truncated output
+[source,yaml]
+----
+spec:
+  developerConfiguration:
+    featureGates:
+      - Snapshot
+----
+
+* Ensure that the VM snapshot includes disks that meet the following requirements:
+** The disks are data volumes or persistent volume claims.
+** The disks belong to a storage class that supports Container Storage Interface (CSI) volume snapshots.
+** The disks are _bound_ to a persistent volume (PV) and _populated_ with a datasource. 
+
 * Install the OpenShift CLI (`oc`).
 * Optional: Power down the VM for which you want to create a snapshot.
 
@@ -40,7 +60,9 @@ $ oc create -f <snapshot_name>.yaml
 +
 The snapshot controller creates a `VirtualMachineSnapshotContent` object, binds it to the `VirtualMachineSnapshot`, and updates the `status` and `readyToUse` fields of the `VirtualMachineSnapshot` object.
 
-. Optional: If you are taking an online snapshot, you can use the `wait` command and monitor the status of the snapshot:
+.Verification
+
+. Optional: During the snapshot creation process, you can use the `wait` command to monitor the status of the snapshot and wait until it is ready for use:
 .. Enter the following command:
 +
 [source,terminal]
@@ -49,9 +71,9 @@ $ oc wait <vm_name> <snapshot_name> --for condition=Ready
 ----
 
 .. Verify the status of the snapshot:
-* `InProgress` - The online snapshot operation is still in progress.
-* `Succeeded` - The online snapshot operation completed successfully.
-* `Failed` - The online snapshot operaton failed.
+* `InProgress` - The snapshot operation is still in progress.
+* `Succeeded` - The snapshot operation completed successfully.
+* `Failed` - The snapshot operaton failed.
 +
 [NOTE]
 ====
@@ -64,8 +86,6 @@ To set no deadline, you can specify `0`, though this is generally not recommende
 If you do not specify a unit of time such as `m` or `s`, the default is seconds (`s`).
 ====
 
-.Verification
-
 . Verify that the `VirtualMachineSnapshot` object is created and bound with `VirtualMachineSnapshotContent` and that the `readyToUse` flag is set to `true`:
 +
 [source,terminal]
@@ -109,10 +129,21 @@ status:
   readyToUse: true <3>
   sourceUID: 355897f3-73a0-4ec4-83d3-3c2df9486f4f
   virtualMachineSnapshotContentName: vmsnapshot-content-28eedf08-5d6a-42c1-969c-2eda58e2a78d <4>
+  indications: <5>
+    - Online
+  includedVolumes: <6>
+    - name: rootdisk
+      kind: PersistentVolumeClaim
+      namespace: default
+    - name: datadisk1
+      kind: DataVolume
+      namespace: default
 ----
 <1> The `status` field of the `Progressing` condition specifies if the snapshot is still being created.
 <2> The `status` field of the `Ready` condition specifies if the snapshot creation process is complete.
 <3> Specifies if the snapshot is ready to be used.
 <4> Specifies that the snapshot is bound to a `VirtualMachineSnapshotContent` object created by the snapshot controller.
+<5> Specifies additional information about the snapshot, such as whether it is an online snapshot, or whether it was created with QEMU guest agent running.
+<6> Lists the storage volumes that are part of the snapshot, as well as their parameters.
 
-. Check the `spec:volumeBackups` property of the `VirtualMachineSnapshotContent` resource to verify that the expected PVCs are included in the snapshot.
+. Check the `includedVolumes` section in the snapshot description to verify that the expected PVCs are included in the snapshot.

modules/virt-creating-vm-snapshot-web.adoc

@@ -8,10 +8,14 @@
 
 You can create a snapshot of a virtual machine (VM) by using the {product-title} web console.
 
-The VM snapshot includes disks that meet the following requirements:
+.Prerequisites
 
-* Either a data volume or a persistent volume claim
-* Belong to a storage class that supports Container Storage Interface (CSI) volume snapshots
+* The `snapshot` feature gate is enabled in the YAML configuration of the `kubevirt` CR.
+
+* The VM snapshot includes disks that meet the following requirements:
+** The disks are data volumes or persistent volume claims.
+** The disks belong to a storage class that supports Container Storage Interface (CSI) volume snapshots.
+** The disks are _bound_ to a persistent volume (PV) and _populated_ with a datasource.
 
 .Procedure
 

modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc

@@ -7,14 +7,13 @@
 [id="virt-installing-qemu-guest-agent-on-linux-vm_{context}"]
 = Installing the QEMU guest agent on a Linux VM
 
-The `qemu-guest-agent` is widely available and available by default in {op-system-base-full} virtual machines (VMs). Install the agent and start the service.
+The `qemu-guest-agent` is available by default in {op-system-base-full} virtual machines (VMs)
 
-[NOTE]
-====
-To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+To create snapshots of a VM in the `Running` state with the highest integrity, install the QEMU guest agent.
 
-The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.
-====
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. 
+
+The conditions under which a snapshot is taken are reflected in the snapshot indications that are displayed in the web console or CLI. If these conditions do not meet your requirements, try creating the snapshot again, or use an offline snapshot
 
 .Procedure
 

modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc

@@ -9,12 +9,13 @@
 
 For Windows virtual machines (VMs), the QEMU guest agent is included in the VirtIO drivers. You can install the drivers during a Windows installation or on an existing Windows VM.
 
-[NOTE]
-====
-To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+To create snapshots of a VM in the `Running` state with the highest integrity, install the QEMU guest agent.
 
-The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.
-====
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. 
+
+Note that in a Windows guest operating system, quiescing also requires the Volume Shadow Copy Service (VSS). Therefore, before you create a snapshot, ensure that VSS is enabled on the VM as well.
+
+The conditions under which a snapshot is taken are reflected in the snapshot indications that are displayed in the web console or CLI. If these conditions do not meet your requirements, try creating the snapshot again or use an offline snapshot.
 
 .Procedure
 

modules/virt-restoring-vm-from-snapshot-cli.adoc

@@ -12,6 +12,12 @@ You can restore an existing virtual machine (VM) to a previous configuration by
 
 * Power down the VM you want to restore.
 
+* Optional: Adjust what happens if the target VM is not fully stopped (_ready_). To do so, set the `targetReadinessPolicy` parameter in the `vmrestore` YAML configuration to one of the following values:
+** `FailImmediate` - The restore process fails immediately if the VM is not ready.
+** `StopTarget` - If the VM is not ready, it gets stopped, and the restore process starts.
+** `WaitGracePeriod 5` - The restore process waits for a set amount of time, in minutes, for the VM to be ready. This is the default setting, with the default value set to 5 minutes.
+** `WaitEventually` - The restore process waits indefinitely for the VM to be ready.
+
 .Procedure
 
 . Create a YAML file to define a `VirtualMachineRestore` object that specifies the name of the VM you want to restore and the name of the snapshot to be used as the source as in the following example:

modules/virt-restoring-vm-from-snapshot-web.adoc

@@ -17,3 +17,9 @@ You can restore a virtual machine (VM) to a previous configuration represented b
 . Select a snapshot to open the *Snapshot Details* screen.
 . Click the Options menu {kebab} and select *Restore VirtualMachine from snapshot*.
 . Click *Restore*.
+
+. Optional: You can also create a new VM based on the snapshot. To do so:  
+.. In the Options menu {kebab} of the the snapshot, select *Create VirtualMachine from Snapshot*.
+.. Provide a name for the new VM.
+.. Click *Create*
+

virt/backup_restore/virt-backup-restore-snapshots.adoc

@@ -17,16 +17,16 @@ ifdef::openshift-rosa,openshift-dedicated[]
 * Any cloud storage provider with the Container Storage Interface (CSI) driver that supports the Kubernetes Volume Snapshot API
 endif::openshift-rosa,openshift-dedicated[]
 
-Online snapshots have a default time deadline of five minutes (`5m`) that can be changed, if needed.
+To create snapshots of a VM in the `Running` state with the highest integrity, install the QEMU guest agent if it is not included with your operating system. The QEMU guest agent is included with the default Red{nbsp}Hat templates.
 
 [IMPORTANT]
 ====
 Online snapshots are supported for virtual machines that have hot plugged virtual disks. However, hot plugged disks that are not in the virtual machine specification are not included in the snapshot.
 ====
 
-To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent if it is not included with your operating system. The QEMU guest agent is included with the default Red Hat templates.
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. 
 
-The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM file system as much as possible, depending on the system workload. This ensures that in-flight I/O is written to the disk before the snapshot is taken. If the guest agent is not present, quiescing is not possible and a best-effort snapshot is taken. The conditions under which the snapshot was taken are reflected in the snapshot indications that are displayed in the web console or CLI.
+The conditions under which a snapshot is taken are reflected in the snapshot indications that are displayed in the web console or CLI. If these conditions do not meet your requirements, try creating the snapshot again or use an offline snapshot
 
 include::modules/virt-about-vm-snapshots.adoc[leveloffset=+1]