CNV-8905: Modifyng snapshot assembly to support online VM snapshots

Author: Bob Gaydos

_topic_map.yml

@@ -2916,8 +2916,8 @@ Topics:
       File: virt-uploading-local-disk-images-virtctl
     - Name: Uploading a local disk image to a block storage data volume
       File: virt-uploading-local-disk-images-block
-    - Name: Managing offline virtual machine snapshots
-      File: virt-managing-offline-vm-snapshots
+    - Name: Managing virtual machine snapshots
+      File: virt-managing-vm-snapshots
     - Name: Moving a local virtual machine disk to a different node
       File: virt-moving-local-vm-disk-to-different-node
     - Name: Expanding virtual storage by adding blank disk images

modules/virt-about-vm-snapshots.adoc

@@ -1,17 +1,20 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 
 [id="virt-about-vm-snapshots_{context}"]
 = About virtual machine snapshots
 
 A _snapshot_ represents the state and data of a virtual machine (VM) at a specific point in time. You can use a snapshot to restore an existing VM to a previous state (represented by
 the snapshot) for backup and disaster recovery or to rapidly roll back to a previous development version.
 
-An offline VM snapshot is created from a VM that is powered off (Stopped state). The snapshot stores a copy of each Container Storage Interface (CSI) volume attached to the VM and a copy of the VM
-specification and metadata. Snapshots cannot be changed after creation.
+A VM snapshot is created from a VM that is powered off (Stopped state) or powred on (Running state).
 
-With the offline VM snapshots feature, cluster administrators and application developers can:
+When taking a snapshot of a running VM, the controller checks that the QEMU guest agent is installed and running. If so, it freezes the VM file system before taking the snapshot, and thaws the file system after the snapshot is taken.
+
+The snapshot stores a copy of each Container Storage Interface (CSI) volume attached to the VM and a copy of the VM specification and metadata. Snapshots cannot be changed after creation.
+
+With the VM snapshots feature, cluster administrators and application developers can:
 
 * Create a new snapshot
 * List all snapshots attached to a specific VM

…rt-creating-offline-vm-snapshot-cli.adoc …dules/virt-creating-vm-snapshot-cli.adocmodules/virt-creating-offline-vm-snapshot-cli.adoc renamed to modules/virt-creating-vm-snapshot-cli.adoc modules/virt-creating-offline-vm-snapshot-cli.adoc renamed to modules/virt-creating-vm-snapshot-cli.adoc

@@ -1,17 +1,24 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 
-[id="virt-creating-offline-vm-snapshot-cli_{context}"]
-= Creating an offline virtual machine snapshot in the CLI
+[id="virt-creating-vm-snapshot-cli_{context}"]
+= Creating an virtual machine snapshot in the CLI
 
-You can create a virtual machine (VM) snapshot for an offline VM by creating a `VirtualMachineSnapshot` object.
+You can create a virtual machine (VM) snapshot for an offline or online VM by creating a `VirtualMachineSnapshot` object. Kubevirt will coordinate with the QEMU guest agent to create a snapshot of the online VM.
+
+[NOTE]
+====
+To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s 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.
+====
 
 .Prerequisites
 
 * Ensure that the persistent volume claims (PVCs) are in a storage class that supports Container Storage Interface (CSI) volume snapshots.
 * Install the OpenShift CLI (`oc`).
-* Power down the VM for which you want to create a snapshot.
+* Optional: Power down the VM for which you want to create a snapshot.
 
 .Procedure
 
@@ -42,6 +49,27 @@ of the `VirtualMachineSnapshot` object.
 $ oc create -f <my-vmsnapshot>.yaml
 ----
 
+. Optional: If you are taking an online snapshot, you can use the `wait` command and monitor the status of the snapshot:
+.. Enter the following command:
++
+[source,terminal]
+----
+$ kubectl wait my-vm my-vmsnapshot --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.
++
+[NOTE]
+====
+Online snapshots have a default time deadline of five (`5`) minutes. If the snapshot does not complete successfully in five minutes, the status is set to `failed`. Afterwards, the file system will be thawed and the VM unfrozen but the status remains `failed` until you delete the failed snapshot image.
+
+To change the default time deadline, add the `FailureDeadline` attribute to the VM snapshot spec with the time (in minutes) that you want to specify before the snapshot operation times out.
+
+To set no deadline, you can specify `0`, though this is generally not recommended, as it can result in an unresponsive VM.
+====
+
 .Verification
 
 . Verify that the `VirtualMachineSnapshot` object is created and bound with `VirtualMachineSnapshotContent`. The `readyToUse` flag must be set to `true`.

…rt-creating-offline-vm-snapshot-web.adoc …dules/virt-creating-vm-snapshot-web.adocmodules/virt-creating-offline-vm-snapshot-web.adoc renamed to modules/virt-creating-vm-snapshot-web.adoc modules/virt-creating-offline-vm-snapshot-web.adoc renamed to modules/virt-creating-vm-snapshot-web.adoc

@@ -1,20 +1,25 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 
-[id="virt-creating-offline-vm-snapshot-web_{context}"]
-= Creating an offline virtual machine snapshot in the web console
+[id="virt-creating-vm-snapshot-web_{context}"]
+= Creating a virtual machine snapshot in the web console
 
 You can create a virtual machine (VM) snapshot by using the web console.
 
+[NOTE]
+====
+To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s 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.
+====
+
 [NOTE]
 ====
 The VM snapshot only includes disks that meet the following requirements:
 
 * Must be either a data volume or persistent volume claim
 * Belong to a storage class that supports Container Storage Interface (CSI) volume snapshots
-
-If your VM storage includes disks that do not support snapshots, you can either edit them or contact your cluster administrator.
 ====
 
 .Procedure

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

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 
 [id="virt-deleting-vm-snapshot-cli_{context}"]
 = Deleting a virtual machine snapshot in the CLI

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

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 
 [id="virt-deleting-vm-snapshot-web_{context}"]
 = Deleting a virtual machine snapshot in the web console

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

@@ -1,12 +1,22 @@
 // Module included in the following assemblies:
 //
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 // * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc
 
 [id="virt-installing-qemu-guest-agent-on-linux-vm_{context}"]
 = Installing QEMU guest agent on a Linux virtual machine
 
 The `qemu-guest-agent` is widely available and available by default in Red Hat
-virtual machines. Install the agent and start the service
+virtual machines. Install the agent and start the service.
+
+To check if your virtual machine (VM) has the QEMU guest agent installed and running, verify that `AgentConnected` is listed in the VM spec.
+
+[NOTE]
+====
+To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s 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.
+====
 
 .Procedure
 

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

@@ -1,9 +1,19 @@
 // Module included in the following assemblies:
 //
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 // * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc
 
-[id="installing-qemu-guest-agent-on-a-windows-virtual-machine"]
+[id="installing-qemu-guest-agent-on-windows-vm_{context}"]
 = Installing QEMU guest agent on a Windows virtual machine
 
 For Windows virtual machines, the QEMU guest agent is included in the
-VirtIO drivers, which can be installed using one of the following procedures:
+VirtIO drivers. Install the drivers on an existng or new Windows system.
+
+To check if your virtual machine (VM) has the QEMU guest agent installed and running, verify that `AgentConnected` is listed in the VM spec.
+
+[NOTE]
+====
+To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+
+The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM’s 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.
+====

modules/virt-installing-virtio-drivers-existing-windows.adoc

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 // * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc
 // * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc
 

modules/virt-installing-virtio-drivers-installing-windows.adoc

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
 // * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc
 // * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc