Merge pull request #66773 from apinnick/qemu-virtio-cleanup

VirtIO installation cleanup

Author: apinnick

modules/virt-about-virtio-drivers.adoc

@@ -5,18 +5,20 @@
 //This file contains UI elements and/or package names that need to be updated.
 
 :_content-type: PROCEDURE
-[id="virt-adding-virtio-drivers-vm-yaml_{context}"]
-= Adding VirtIO drivers container disk to a virtual machine
+[id="virt-adding-container-disk-as-cd_{context}"]
+= Installing VirtIO drivers from a container disk added as a SATA CD drive
 
-You can add a VirtIO drivers container disk to a Windows virtual machine (VM) as a SATA CD drive.
-
-VirtIO drivers are paravirtualized device drivers required for Microsoft Windows VMs to run in {VirtProductName}.
+You can install VirtIO drivers from a container disk that you add to a Windows virtual machine (VM) as a SATA CD drive.
 
 [TIP]
 ====
 Downloading the `container-native-virtualization/virtio-win` container disk from the link:https://catalog.redhat.com/software/containers/search?q=virtio-win&p=1[Red Hat Ecosystem Catalog] is not mandatory, because the container disk is downloaded from the Red Hat registry if it not already present in the cluster. However, downloading reduces the installation time.
 ====
 
+.Prerequisites
+
+* You must have access to the Red Hat registry or to the downloaded `container-native-virtualization/virtio-win` container disk in a restricted environment.
+
 .Procedure
 
 . Add the `container-native-virtualization/virtio-win` container disk as a CD drive by editing the `VirtualMachine` manifest:
@@ -44,14 +46,14 @@ volumes:
 +
 [source,terminal]
 ----
- $ `virtctl start <vm>`
+$ virtctl start <vm>
 ----
 
 * If the VM is running, reboot the VM or run the following command:
 +
 [source,terminal]
 ----
-$ run `oc apply -f <vm.yaml>`
+$ oc apply -f <vm.yaml>
 ----
 
-. After the virtual machine has started, install the VirtIO drivers from the SATA CD drive.
+. After the VM has started, install the VirtIO drivers from the SATA CD drive.

modules/virt-adding-virtio-drivers-vm-yaml.adoc renamed to modules/virt-adding-container-disk-as-cd.adoc

@@ -5,22 +5,22 @@
 
 :_content-type: PROCEDURE
 [id="virt-installing-qemu-guest-agent-on-linux-vm_{context}"]
-= Installing QEMU guest agent on a Linux virtual machine
+= 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.
 
 [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.
+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.
 ====
 
 .Procedure
 
-. Access the virtual machine command line through one of the consoles or by SSH.
+. Log in to the VM by using a console or SSH.
 
-. Install the QEMU guest agent on the virtual machine:
+. Install the QEMU guest agent by running the following command:
 +
 [source,terminal]
 ----
@@ -35,7 +35,7 @@ $ systemctl enable --now qemu-guest-agent
 ----
 
 .Verification
-. Run the following command to verify that `AgentConnected` is listed in the VM spec:
+* Run the following command to verify that `AgentConnected` is listed in the VM spec:
 
 +
 [source,terminal]

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

@@ -5,30 +5,28 @@
 
 :_content-type: PROCEDURE
 [id="installing-qemu-guest-agent-on-windows-vm_{context}"]
-= Installing QEMU guest agent on a Windows virtual machine
+= Installing the QEMU guest agent on a Windows VM
 
-For Windows virtual machines, the QEMU guest agent is included in the
-VirtIO drivers. Install the drivers on an existing or a new Windows installation.
+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.
 
-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 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.
 ====
 
 .Procedure
 
-. In the Windows Guest Operating System (OS), use the *File Explorer* to navigate to the `guest-agent` directory in the `virtio-win` CD drive.
-
+. In the Windows guest operating system, use the *File Explorer* to navigate to the `guest-agent` directory in the `virtio-win` CD drive.
 . Run the `qemu-ga-x86_64.msi` installer.
 
-
 .Verification
-. Run the following command to verify that the output contains the `QEMU Guest Agent`:
-
+. Obtain a list of network services by running the following command:
 +
 [source,terminal]
 ----
 $ net start
-----
+----
+
+. Verify that the output contains the `QEMU Guest Agent`.

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

@@ -5,28 +5,29 @@
 
 :_content-type: PROCEDURE
 [id="virt-installing-virtio-drivers-existing-windows_{context}"]
-= Installing VirtIO drivers on an existing Windows virtual machine
+= Installing VirtIO drivers from a SATA CD drive on an existing Windows VM
 
-Install the VirtIO drivers from the attached SATA CD drive to an
-existing Windows virtual machine.
+You can install the VirtIO drivers from a SATA CD drive on an existing Windows virtual machine (VM).
 
 [NOTE]
 ====
-This procedure uses a generic approach to adding drivers to Windows.
-The process might differ slightly between versions of Windows.
-See the installation documentation for your version of Windows
-for specific installation steps.
+This procedure uses a generic approach to adding drivers to Windows. See the installation documentation for your version of Windows for specific installation steps.
 ====
 
+.Prerequisites
+
+* A storage device containing the virtio drivers must be attached to the VM as a SATA CD drive.
+
 .Procedure
 
-. Start the virtual machine and connect to a graphical console.
+. Start the VM and connect to a graphical console.
 . Log in to a Windows user session.
 . Open *Device Manager* and expand *Other devices* to list any *Unknown device*.
-.. Open the `Device Properties` to identify the unknown device.
-Right-click the device and select *Properties*.
+.. Open the *Device Properties* to identify the unknown device.
+.. Right-click the device and select *Properties*.
 .. Click the *Details* tab and select *Hardware Ids* in the *Property* list.
 .. Compare the *Value* for the *Hardware Ids* with the supported VirtIO drivers.
+
 . Right-click the device and select *Update Driver Software*.
 . Click *Browse my computer for driver software* and browse to the attached
 SATA CD drive, where the VirtIO drivers are located. The drivers are arranged
@@ -35,4 +36,4 @@ and CPU architecture.
 . Click *Next* to install the driver.
 . Repeat this process for all the necessary VirtIO drivers.
 . After the driver installs, click *Close* to close the window.
-. Reboot the virtual machine to complete the driver installation.
+. Reboot the VM to complete the driver installation.

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

@@ -2,19 +2,16 @@
 //
 // * virt/backup_restore/virt-managing-vm-snapshots.adoc
 // * virt/virtual_machines/creating_vms/virt-installing-qemu-guest-agent.adoc
-// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc
 
 :_content-type: PROCEDURE
 [id="virt-installing-virtio-drivers-installing-windows_{context}"]
 = Installing VirtIO drivers during Windows installation
 
-Install the `virtio` drivers during or after Windows installation.
+You can install the VirtIO drivers while installing Windows on a virtual machine (VM).
 
 [NOTE]
 ====
-This procedure uses a generic approach to the Windows installation and the
-installation method might differ between versions of Windows. See the
-documentation for the version of Windows that you are installing.
+This procedure uses a generic approach to the Windows installation and the installation method might differ between versions of Windows. See the documentation for the version of Windows that you are installing.
 ====
 
 .Prerequisites
@@ -23,8 +20,8 @@ documentation for the version of Windows that you are installing.
 
 .Procedure
 
-. In the Windows Guest OS, use the `File Explorer` to navigate to the `virtio-win` CD drive.
-. Double-click the drive to run the appropriate installer for your VM:
+. In the Windows operating system, use the `File Explorer` to navigate to the `virtio-win` CD drive.
+. Double-click the drive to run the appropriate installer for your VM.
 +
 For a 64-bit vCPU, select the `virtio-win-gt-x64` installer. 32-bit vCPUs are no longer supported.
 
@@ -35,6 +32,6 @@ For a 64-bit vCPU, select the `virtio-win-gt-x64` installer. 32-bit vCPUs are no
 .Verification
 
 . Open the system disk on the PC. This is typically `C:`.
-. Navigate to *Program Files*  -> *Virtio-Win*.
+. Navigate to *Program Files* -> *Virtio-Win*.
 
 If the *Virtio-Win* directory is present and contains a sub-directory for each driver, the installation was successful.

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

@@ -5,18 +5,18 @@
 
 :_content-type: PROCEDURE
 [id="virt-updating-virtio-drivers-windows_{context}"]
-= Updating VirtIO drivers on a Windows guest
+= Updating VirtIO drivers on a Windows VM
 
-Update the `virtio` drivers by using Windows Update.
+Update the `virtio` drivers on a Windows virtual machine (VM) by using the Windows Update service.
 
 .Prerequisites
 
-* A Windows guest operating system with the `virtio` drivers must be attached to the virtual machine (VM).
 * The cluster must be connected to the internet. Disconnected clusters cannot reach the Windows Update service.
 
 .Procedure
 
-. In the Windows Guest operating system, use the `File Explorer` to navigate to *Settings* -> *Windows Update* -> *Advanced Options* -> *Optional Updates*.
+. In the Windows Guest operating system, click the *Windows* key and select *Settings*.
+. Navigate to *Windows Update* -> *Advanced Options* -> *Optional Updates*.
 . Install all updates from *Red Hat, Inc.*.
 . Reboot the VM.
 
@@ -25,4 +25,4 @@ Update the `virtio` drivers by using Windows Update.
 . On the Windows VM, navigate to the *Device Manager*.
 . Select a device.
 . Select the *Driver* tab.
-. Click *Driver Details* and confirm that the `virtio` driver details list the correct version.
+. Click *Driver Details* and confirm that the `virtio` driver details displays the correct version.

modules/virt-supported-virtio-drivers.adoc

@@ -18,19 +18,43 @@ include::modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc[leveloffset=+
 include::modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc[leveloffset=+2]
 
 [id="installing-virtio-drivers"]
-== Installing VirtIO drivers
+== Installing VirtIO drivers on Windows VMs
 
-include::modules/virt-supported-virtio-drivers.adoc[leveloffset=+2]
+VirtIO drivers are paravirtualized device drivers required for Microsoft Windows virtual machines (VMs) to run in {VirtProductName}. The supported drivers are
+available in the `container-native-virtualization/virtio-win` container disk of the link:https://catalog.redhat.com/software/containers/search?q=virtio-win&p=1[Red Hat Ecosystem Catalog].
 
-include::modules/virt-about-virtio-drivers.adoc[leveloffset=+2]
+The `container-native-virtualization/virtio-win` container disk must be attached to the VM as a SATA CD drive to enable driver installation. You can install VirtIO drivers during Windows installation or added to an existing Windows installation.
 
-include::modules/virt-installing-virtio-drivers-existing-windows.adoc[leveloffset=+2]
+After the drivers are installed, the `container-native-virtualization/virtio-win` container disk can be removed from the VM.
+
+.Supported drivers
+[options="header"]
+|===
+|Driver name |Hardware ID |Description
+
+|*viostor*
+|VEN_1AF4&DEV_1001 +
+VEN_1AF4&DEV_1042
+|The block driver. Sometimes labeled as an *SCSI Controller* in the *Other devices* group.
+
+|*viorng*
+|VEN_1AF4&DEV_1005 +
+VEN_1AF4&DEV_1044
+|The entropy source driver. Sometimes labeled as a *PCI Device* in the *Other devices* group.
+
+|*NetKVM*
+|VEN_1AF4&DEV_1000 +
+VEN_1AF4&DEV_1041
+|The network driver. Sometimes labeled as an *Ethernet Controller* in the *Other devices* group. Available only if a VirtIO NIC is configured.
+|===
 
 include::modules/virt-installing-virtio-drivers-installing-windows.adoc[leveloffset=+2]
 
-include::modules/virt-adding-virtio-drivers-vm-yaml.adoc[leveloffset=+2]
+include::modules/virt-installing-virtio-drivers-existing-windows.adoc[leveloffset=+2]
+
+include::modules/virt-adding-container-disk-as-cd.adoc[leveloffset=+2]
 
 [id="updating-virtio-drivers"]
 == Updating VirtIO drivers
 
-include::modules/virt-updating-virtio-drivers-windows.adoc[leveloffset=+2]
+include::modules/virt-updating-virtio-drivers-windows.adoc[leveloffset=+2]