Merge pull request #36592 from bgaydosrh/CNV-8905

adellape · web-flow · commit 6c47489403e9 · 2021-09-29T13:48:05.000-06:00
diff --git a/_topic_map.yml b/_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
diff --git a/modules/virt-about-vm-snapshots.adoc b/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
diff --git a/modules/virt-creating-vm-snapshot-cli.adoc b/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`.
diff --git a/modules/virt-creating-vm-snapshot-web.adoc b/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
diff --git a/modules/virt-deleting-vm-snapshot-cli.adoc b/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
diff --git a/modules/virt-deleting-vm-snapshot-web.adoc b/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
diff --git a/modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc b/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
 
diff --git a/modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc b/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.
+====
diff --git a/modules/virt-installing-virtio-drivers-existing-windows.adoc b/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
 
diff --git a/modules/virt-installing-virtio-drivers-installing-windows.adoc b/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
 
diff --git a/modules/virt-restoring-vm-from-snapshot-cli.adoc b/modules/virt-restoring-vm-from-snapshot-cli.adoc
@@ -1,11 +1,11 @@
 // 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-restoring-vm-from-snapshot-cli_{context}"]
 = Restoring a virtual machine from a snapshot in the CLI
 
-You can restore an existing virtual machine (VM) to a previous configuration by using a VM snapshot .
+You can restore an existing virtual machine (VM) to a previous configuration by using a VM snapshot. You can only restore from an offline VM snapshot.
 
 .Prerequisites
 
diff --git a/modules/virt-restoring-vm-from-snapshot-web.adoc b/modules/virt-restoring-vm-from-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-restoring-vm-from-snapshot-web_{context}"]
 = Restoring a virtual machine from a snapshot in the web console
diff --git a/modules/virt-verifying-online-snapshot-creation-with-snapshot-indications.adoc b/modules/virt-verifying-online-snapshot-creation-with-snapshot-indications.adoc
@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
+
+[id="virt-verifying-online-snapshot-creation-with-snapshot-indications_{context}"]
+= Verifying online snapshot creation with snapshot indications
+
+Snapshot indications are contextual information about online virtual machine (VM) snapshot operations. Indications are not available for offline virtual machine (VM) snapshot operations. Indications are helpful in describing details about the online snapshot creation.
+
+.Prerequisites
+
+* To view indications, you must have attempted to create an online VM snapshot using the CLI or the web console.
+
+.Procedure
+
+. Display the output from the snapshot indications by doing one of the following:
+* For snapshots created with the CLI, view indicator output in the `VirtualMachineSnapshot` object YAML, in the *status* field.
+* For snapshots created using the web console, click *VirtualMachineSnapshot > Status* in the *Snapshot details* screen.
+. Verify the status of your online VM snapshot:
+* `Online` indicates that the VM was running during online snapshot creation.
+* `NoGuestAgent` indicates that the QEMU guest agent was not running during online snapshot creation. The QEMU guest agent could not be used to freeze and thaw the file system, either because the QEMU guest agent was not installed or running or due to another error.
diff --git a/virt/virt-learn-more-about-openshift-virtualization.adoc b/virt/virt-learn-more-about-openshift-virtualization.adoc
@@ -86,7 +86,7 @@ Use the following tables to find content to help you learn about and use {VirtPr
 
 |
 | xref:../virt/virtual_machines/virt-manage-vmis.adoc#virt-manage-vmis[Managing virtual machines instances]
-| xref:../virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc#virt-managing-offline-vm-snapshots[Creating and managing virtual machine snapshots]
+| xref:../virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc#virt-managing-vm-snapshots[Creating and managing virtual machine snapshots]
 |
 
 |
diff --git a/virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc b/virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc
diff --git a/virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc b/virt/virtual_machines/virtual_disks/virt-managing-vm-snapshots.adoc
@@ -0,0 +1,51 @@
+[id="virt-managing-vm-snapshots"]
+= Managing virtual machine snapshots
+include::modules/virt-document-attributes.adoc[]
+:context: virt-managing-vm-snapshots
+
+toc::[]
+
+You can create and delete virtual machine (VM) snapshots for VMs, whether the VMs are powered off (offline) or on (online). You can only restore to a powered off (offline) VM. {VirtProductName} supports VM snapshots on the following:
+
+* Red Hat OpenShift Container Storage
+* Any other storage provider with the Container Storage Interface (CSI) driver that supports the Kubernetes Volume Snapshot API
+
+[IMPORTANT]
+====
+Online snapshots are not supported for virtual machines that have hot-plugged virtual disks.
+====
+
+[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.
+====
+
+include::modules/virt-about-vm-snapshots.adoc[leveloffset=+1]
+
+include::modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc[leveloffset=+1]
+
+include::modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc[leveloffset=+1]
+
+include::modules/virt-installing-virtio-drivers-existing-windows.adoc[leveloffset=+2]
+
+include::modules/virt-installing-virtio-drivers-installing-windows.adoc[leveloffset=+2]
+
+include::modules/virt-creating-vm-snapshot-web.adoc[leveloffset=+1]
+
+include::modules/virt-creating-vm-snapshot-cli.adoc[leveloffset=+1]
+
+include::modules/virt-verifying-online-snapshot-creation-with-snapshot-indications.adoc[leveloffset=+1]
+
+include::modules/virt-restoring-vm-from-snapshot-web.adoc[leveloffset=+1]
+
+include::modules/virt-restoring-vm-from-snapshot-cli.adoc[leveloffset=+1]
+
+include::modules/virt-deleting-vm-snapshot-web.adoc[leveloffset=+1]
+
+include::modules/virt-deleting-vm-snapshot-cli.adoc[leveloffset=+1]
+
+== Additional resources
+
+* xref:../../../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[CSI Volume Snapshots]
