Merge pull request #63512 from apinnick/fixes

Organize snapshots assembly, update block PVs

Author: apinnick

modules/virt-about-block-pvs.adoc

@@ -1,10 +1,9 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc
+// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc
 // * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc
 // * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-block-storage-pvc.adoc
 
-
 :_content-type: CONCEPT
 [id="virt-about-block-pvs_{context}"]
 = About block persistent volumes

modules/virt-about-vm-snapshots.adoc

@@ -4,7 +4,7 @@
 
 :_content-type: CONCEPT
 [id="virt-about-vm-snapshots_{context}"]
-= About virtual machine snapshots
+= About 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.
@@ -15,17 +15,16 @@ When taking a snapshot of a running VM, the controller checks that the QEMU gues
 
 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:
+You can perform the following snapshot actions:
 
 * Create a new snapshot
 * List all snapshots attached to a specific VM
 * Restore a VM from a snapshot
 * Delete an existing VM snapshot
 
-[id="vm-snapshot-controller-and-crds_{context}"]
-== Virtual machine snapshot controller and custom resource definitions (CRDs)
+.VM snapshot controller and custom resources
 
-The VM snapshot feature introduces three new API objects defined as CRDs for managing snapshots:
+The VM snapshot feature introduces three new API objects defined as custom resource definitions (CRDs) for managing snapshots:
 
 * `VirtualMachineSnapshot`: Represents a user request to create a snapshot. It contains information about the current state of the VM.
 * `VirtualMachineSnapshotContent`: Represents a provisioned resource on the cluster (a snapshot). It is created by the VM snapshot controller and contains references to all resources required to restore the VM.

modules/virt-configuring-secondary-network-vm-live-migration.adoc

@@ -1,24 +1,23 @@
 // Module included in the following assemblies:
 //
-// * virt/live_migration/virt-migrating-vm-on-secondary-network.adoc
+// * virt/vm_networking/virt-dedicated-network-live-migration.adoc
 
 :_content-type: PROCEDURE
 [id="virt-configuring-secondary-network-vm-live-migration_{context}"]
 = Configuring a dedicated secondary network for virtual machine live migration
 
-To configure a dedicated secondary network for live migration, you must first create a bridge network attachment definition for the `openshift-cnv` namespace by using the CLI. Then, add the name of the `NetworkAttachmentDefinition` object to the `HyperConverged` custom resource (CR).
+To configure a dedicated secondary network for live migration, you must first create a bridge network attachment definition (NAD) by using the CLI. Then, you add the name of the `NetworkAttachmentDefinition` object to the `HyperConverged` custom resource (CR).
 
 .Prerequisites
 
 * You installed the OpenShift CLI (`oc`).
 * You logged in to the cluster as a user with the `cluster-admin` role.
-* The Multus Container Network Interface (CNI) plugin is installed on the cluster.
-* Every node on the cluster has at least two Network Interface Cards (NICs), and the NICs to be used for live migration are connected to the same VLAN.
-* The virtual machine (VM) is running with the `LiveMigrate` eviction strategy.
+* Each node has at least two Network Interface Cards (NICs).
+* The NICs for live migration are connected to the same VLAN.
 
 .Procedure
 
-. Create a `NetworkAttachmentDefinition` manifest.
+. Create a `NetworkAttachmentDefinition` manifest according to the following example:
 +
 .Example configuration file
 [source,yaml,subs="attributes+"]
@@ -33,19 +32,18 @@ spec:
     "cniVersion": "0.3.1",
     "name": "migration-bridge",
     "type": "macvlan",
-    "master": "eth1", <3>
+    "master": "eth1", <2>
     "mode": "bridge",
     "ipam": {
-      "type": "whereabouts", <4>
-      "range": "10.200.5.0/24" <5>
+      "type": "whereabouts", <3>
+      "range": "10.200.5.0/24" <4>
     }
   }'
 ----
-<1> The name of the `NetworkAttachmentDefinition` object.
-<2> The namespace where the `NetworkAttachmentDefinition` object resides. This must be `openshift-cnv`.
-<3> The name of the NIC to be used for live migration.
-<4> The name of the CNI plugin that provides the network for this network attachment definition.
-<5> The IP address range for the secondary network. This range must not have any overlap with the IP addresses of the main network.
+<1> Specify the name of the `NetworkAttachmentDefinition` object.
+<2> Specify the name of the NIC to be used for live migration.
+<3> Specify the name of the CNI plugin that provides the network for the NAD.
+<4> Specify an IP address range for the secondary network. This range must not overlap the IP addresses of the main network.
 
 . Open the `HyperConverged` CR in your default editor by running the following command:
 +
@@ -56,7 +54,7 @@ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
 
 . Add the name of the `NetworkAttachmentDefinition` object to the `spec.liveMigrationConfig` stanza of the `HyperConverged` CR. For example:
 +
-.Example configuration file
+.Example `HyperConverged` manifest
 [source,yaml]
 ----
 apiVersion: hco.kubevirt.io/v1beta1
@@ -66,14 +64,13 @@ metadata:
 spec:
   liveMigrationConfig:
     completionTimeoutPerGiB: 800
-    network: my-secondary-network  <1>
+    network: <network> <1>
     parallelMigrationsPerCluster: 5
     parallelOutboundMigrationsPerNode: 2
     progressTimeout: 150
 # ...
 ----
-<1> The name of the Multus `NetworkAttachmentDefinition` object to be used for live migrations.
-
+<1> Specify the name of the Multus `NetworkAttachmentDefinition` object to be used for live migrations.
 
 . Save your changes and exit the editor. The `virt-handler` pods restart and connect to the secondary network.
 
@@ -83,5 +80,5 @@ spec:
 +
 [source,terminal]
 ----
-oc get vmi <vmi_name> -o jsonpath='{.status.migrationState.targetNodeAddress}'
+$ oc get vmi <vmi_name> -o jsonpath='{.status.migrationState.targetNodeAddress}'
 ----

modules/virt-creating-local-block-pv.adoc

@@ -4,7 +4,6 @@
 // * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc
 // * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-block-storage-pvc.adoc
 
-
 :_content-type: PROCEDURE
 [id="virt-creating-local-block-pv_{context}"]
 = Creating a local block persistent volume
@@ -18,25 +17,24 @@ virtual machine image.
 
 .Procedure
 
-. Log in as `root` to the node on which to create the local PV. This procedure
+. Log in as root user to the node on which to create the local PV. This procedure
 uses `node01` for its examples.
 
 . Create a file and populate it with null characters so that it can be used as a block device.
 The following example creates a file `loop10` with a size of 2Gb (20 100Mb blocks):
 +
 [source,terminal]
 ----
-$ dd if=/dev/zero of=<loop10> bs=100M count=20
+# dd if=/dev/zero of=loop10 bs=100M count=20
 ----
 
-. Mount the `loop10` file as a loop device.
+. Mount the `loop10` file as a loop device as in the following example:
 +
 [source,terminal]
 ----
-$ losetup </dev/loop10>d3 <loop10> <1> <2>
+# losetup /path/loop10 loop10 <1>
 ----
-<1> File path where the loop device is mounted.
-<2> The file created in the previous step to be mounted as the loop device.
+<1> Specify the path of the loop device and the loop device file name.
 
 . Create a `PersistentVolume` manifest that references the mounted loop device.
 +
@@ -71,7 +69,7 @@ spec:
 <3> Optional: Set a storage class for the PV. If you omit it, the cluster default is used.
 <4> The node on which the block device was mounted.
 
-. Create the block PV.
+. Create the block PV:
 +
 [source,terminal]
 ----

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

@@ -4,16 +4,9 @@
 
 :_content-type: PROCEDURE
 [id="virt-creating-vm-snapshot-cli_{context}"]
-= Creating a virtual machine snapshot in the CLI
+= Creating a snapshot by using the command line
 
-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.
-====
+You can create a virtual machine (VM) snapshot for an offline or online VM by creating a `VirtualMachineSnapshot` object.
 
 .Prerequisites
 
@@ -23,40 +16,38 @@ The QEMU guest agent takes a consistent snapshot by attempting to quiesce the VM
 
 .Procedure
 
-. Create a YAML file to define a `VirtualMachineSnapshot` object that specifies the name of the new `VirtualMachineSnapshot` and the name of the source VM.
-+
-For example:
+. Create a YAML file to define a `VirtualMachineSnapshot` object that specifies the name of the new `VirtualMachineSnapshot` and the name of the source VM as in the following example:
 +
 [source,yaml]
 ----
 apiVersion: snapshot.kubevirt.io/v1beta1
 kind: VirtualMachineSnapshot
 metadata:
-  name: my-vmsnapshot <1>
+  name: <snapshot_name>
 spec:
   source:
     apiGroup: kubevirt.io
     kind: VirtualMachine
-    name: my-vm <2>
+    name: <vm_name>
 ----
-<1> The name of the new `VirtualMachineSnapshot` object.
-<2> The name of the source VM.
 
-. Create the `VirtualMachineSnapshot` resource. The snapshot controller creates a `VirtualMachineSnapshotContent` object, binds it to the `VirtualMachineSnapshot` and updates the `status` and `readyToUse` fields
-of the `VirtualMachineSnapshot` object.
+. Create the `VirtualMachineSnapshot` object:
 +
 [source,terminal]
 ----
-$ oc create -f <my-vmsnapshot>.yaml
+$ 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:
 .. Enter the following command:
 +
 [source,terminal]
 ----
-$ oc wait my-vm my-vmsnapshot --for condition=Ready
+$ 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.
@@ -75,15 +66,14 @@ If you do not specify a unit of time such as `m` or `s`, the default is seconds
 
 .Verification
 
-. Verify that the `VirtualMachineSnapshot` object is created and bound with `VirtualMachineSnapshotContent`. The `readyToUse` flag must be set to `true`.
+. Verify that the `VirtualMachineSnapshot` object is created and bound with `VirtualMachineSnapshotContent` and that the `readyToUse` flag is set to `true`:
 +
 [source,terminal]
 ----
-$ oc describe vmsnapshot <my-vmsnapshot>
+$ oc describe vmsnapshot <snapshot_name>
 ----
 +
 .Example output
-
 [source,yaml]
 ----
 apiVersion: snapshot.kubevirt.io/v1beta1

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

@@ -4,36 +4,22 @@
 
 :_content-type: PROCEDURE
 [id="virt-creating-vm-snapshot-web_{context}"]
-= Creating a virtual machine snapshot in the web console
+= Creating a snapshot by using the web console
 
-You can create a virtual machine (VM) snapshot by using the web console.
+You can create a snapshot of a virtual machine (VM) by using the {product-title} web console.
 
-[NOTE]
-====
-To create snapshots of an online (Running state) VM with the highest integrity, install the QEMU guest agent.
+The VM snapshot includes disks that meet the following requirements:
 
-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.
-====
-
-The VM snapshot only includes disks that meet the following requirements:
-
-* Must be either a data volume or persistent volume claim
+* Either a data volume or a persistent volume claim
 * Belong to a storage class that supports Container Storage Interface (CSI) volume snapshots
 
 .Procedure
 
-. Click *Virtualization* -> *VirtualMachines* from the side menu.
-
-. Select a virtual machine to open the *VirtualMachine details* page.
-
-. If the virtual machine is running, click *Actions* → *Stop* to power it down.
-
+. Navigate to *Virtualization* -> *VirtualMachines* in the web console.
+. Select a VM to open the *VirtualMachine details* page.
+. If the VM is running, click the options menu {kebab} and select *Stop* to power it down.
 . Click the *Snapshots* tab and then click *Take Snapshot*.
-
-. Fill in the *Snapshot Name* and optional *Description* fields.
-
+. Enter the snapshot name.
 . Expand *Disks included in this Snapshot* to see the storage volumes to be included in the snapshot.
-
-. If your VM has disks that cannot be included in the snapshot and you still wish to proceed, select the *I am aware of this warning and wish to proceed* checkbox.
-
+. If your VM has disks that cannot be included in the snapshot and you wish to proceed, select *I am aware of this warning and wish to proceed*.
 . Click *Save*.

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

@@ -14,12 +14,14 @@ You can delete an existing virtual machine (VM) snapshot by deleting the appropr
 
 .Procedure
 
-* Delete the `VirtualMachineSnapshot` object. The snapshot controller deletes the `VirtualMachineSnapshot` along with the associated `VirtualMachineSnapshotContent` object.
+* Delete the `VirtualMachineSnapshot` object:
 +
 [source,terminal]
 ----
-$ oc delete vmsnapshot <my-vmsnapshot>
+$ oc delete vmsnapshot <snapshot_name>
 ----
++
+The snapshot controller deletes the `VirtualMachineSnapshot` along with the associated `VirtualMachineSnapshotContent` object.
 
 .Verification
 

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

@@ -4,18 +4,14 @@
 
 :_content-type: PROCEDURE
 [id="virt-deleting-vm-snapshot-web_{context}"]
-= Deleting a virtual machine snapshot in the web console
+= Deleting a snapshot by using the web console
 
-You can delete an existing virtual machine snapshot by using the web console.
+You can delete an existing virtual machine (VM) snapshot by using the web console.
 
 .Procedure
 
-. Click *Virtualization* -> *VirtualMachines* from the side menu.
-
-. Select a virtual machine to open the *VirtualMachine details* page.
-
-. Click the *Snapshots* tab. The page displays a list of snapshots associated with the virtual machine.
-
-. Click the Options menu {kebab} of the virtual machine snapshot that you want to delete and select *Delete VirtualMachineSnapshot*.
-
-. In the confirmation pop-up window, click *Delete* to delete the snapshot.
+. Navigate to *Virtualization* -> *VirtualMachines* in the web console.
+. Select a VM to open the *VirtualMachine details* page.
+. Click the *Snapshots* tab to view a list of snapshots associated with the VM.
+. Click the options menu {kebab} beside a snapshot and select *Delete VirtualMachineSnapshot*.
+. Click *Delete*.