[enterprise-3.11] CNV virtio drivers

cnv_users_guide/cnv_users_guide.adoc

@@ -71,6 +71,14 @@ include::modules/cnv_blankdisk_pvc.adoc[leveloffset=+2]
 == Creating virtual machines in {product-title}
 include::modules/cnv_creating_vm.adoc[leveloffset=+2]
 
+[[cnv_userguide_virtio_drivers]]
+== `virtio` drivers for Microsoft Windows virtual machines
+include::modules/cnv_virtio_drivers.adoc[leveloffset=+2]
+include::modules/cnv_adding_virtio_drivers_vm_yaml.adoc[leveloffset=+2]
+include::modules/cnv_installing_virtio_drivers_installing_windows.adoc[leveloffset=+2]
+include::modules/cnv_installing_virtio_drivers_existing_windows.adoc[leveloffset=+2]
+include::modules/cnv_removing_virtio_disk_from_vm.adoc[leveloffset=+2]
+
 [[cnv_userguide_using_vms_openshift]]
 == Using virtual machines in {product-title}
 include::modules/cnv_accessing_serial_console.adoc[leveloffset=+2]
@@ -103,10 +111,12 @@ include::modules/cnv_cloud_init_fields_web.adoc[leveloffset=+2]
 include::modules/cnv_networking_wizard_fields_web.adoc[leveloffset=+2]
 include::modules/cnv_storage_wizard_fields_web.adoc[leveloffset=+2]
 include::modules/cnv_vm_actions_web.adoc[leveloffset=+2]
+include::modules/cnv_supported_virtio_drivers.adoc[leveloffset=+2]
 include::modules/cnv_vm_storage_volume_types.adoc[leveloffset=+1]
 include::modules/cnv_template_pvc_config.adoc[leveloffset=+1]
 include::modules/cnv_template_vm_config.adoc[leveloffset=+1]
 include::modules/cnv_template_dv_config.adoc[leveloffset=+1]
 include::modules/cnv_template_import_dv.adoc[leveloffset=+1]
 include::modules/cnv_template_clone_DV.adoc[leveloffset=+1]
 include::modules/cnv_template_vmi_pxe_config.adoc[leveloffset=+1]
+

modules/cnv_adding_virtio_drivers_vm_yaml.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-adding-virtio-drivers-vm-yaml]]
+= Adding VirtIO drivers container disk to a virtual machine
+
+{ProductName} distributes VirtIO drivers for Microsoft Windows as a container disk, available from the Red Hat Container Catalog. To xref:cnv-installing-virtio-drivers-installing-windows[install] or xref:cnv-installing-virtio-drivers-existing-windows[add] these drivers to a Windows virtual machine, attach the `virtio-win` container disk to the virtual machine as a SATA CD drive. 
+
+.Procedure
+
+* Add the `cnv-tech-preview/virtio-win` container disk as a `cdrom` disk in the Windows virtual machine configuration file. The container disk will be downloaded from the registry if it is not already present in the cluster. 
+
+[source,yaml]
+----
+spec:
+  domain:
+    devices:
+      disks:
+        - name: virtiocontainerdisk
+          bootOrder: 2 <1>
+          cdrom:
+            bus: sata
+volumes:
+  - containerDisk:
+      image: cnv-tech-preview/virtio-win
+    name: virtiocontainerdisk
+----
+<1> {ProductName} boots virtual machines disks in the order defined in the `VirtualMachine` configuration file. You can either define other disks for the virtual machine before the `virtio-win` container disk, or use the optional `bootOrder` parameter to ensure the virtual machine boots from the correct disk. If you specify the `bootOrder` for a disk, it must be specified for all disks in the configuration.
+
+After the virtual machine has been created and started, the VirtIO drivers can be installed from the attached SATA CD drive xref:cnv-installing-virtio-drivers-installing-windows[during Windows installation on the virtual machine], or xref:cnv-installing-virtio-drivers-existing-windows[added to an existing Windows installation].
+
+After the drivers have been installed, you can xref:cnv-removing-virtio-disk-from-vm[remove the `virtio-win` container disk] from the virtual machine. 
+

modules/cnv_installing_virtio_drivers_existing_windows.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-installing-virtio-drivers-existing-windows]]
+= Installing VirtIO drivers on an existing Windows virtual machine
+
+Install VirtIO drivers on an existing Windows virtual machine. 
+
+.Prerequisites
+
+* Windows virtual machine with xref:cnv-adding-virtio-drivers-vm-yaml[VirtIO drivers container disk attached as a SATA CD drive].
+
+[NOTE]
+====
+This procedure uses a generic approach to adding drivers to Windows. The process may differ slightly between versions of Windows. Refer to the documentation for the version of Windows that you are installing.
+====
+
+.Procedure
+
+. Start the virtual machine and connect to a graphical console.
+. Log in to a Windows user session.
+. Open *Device Manager* and expand *Other devices* to xref:cnv-supported-virtio-drivers[list any *Unknown device*].
+.. You may need to 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 drop-down list.
+.. Compare the *Value* for the *Hardware Ids* with the xref:cnv-supported-virtio-drivers[supported VirtIO drivers].
+. Right-click the device and select *Update Driver Software*.
+. Click *Browse my computer for driver software* and browse to the location of the driver. The drivers are arranged hierarchically according to their driver type, operating system, and CPU architecture.
+. Click *Next* to install the driver. 
+. After the driver installs, click *Close* to close the window.
+. Reboot the virtual machine to complete the driver installation. 
+
+After the drivers have been installed, you can xref:cnv-removing-virtio-disk-from-vm[remove the disk] from the virtual machine configuration file. 
+

modules/cnv_installing_virtio_drivers_installing_windows.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-installing-virtio-drivers-installing-windows]]
+= Installing VirtIO drivers during Windows installation
+
+Install the VirtIO drivers during Windows installation to the virtual machine. At a minimum, you must install a xref:cnv-supported-virtio-drivers[supported storage driver] to select the storage destination for the Windows installation. 
+
+.Prerequisites
+
+* Virtual machine with xref:cnv-adding-virtio-drivers-vm-yaml[VirtIO drivers container disk attached as a SATA CD drive].
+* Windows installation media accessible by the virtual machine.
+
+[NOTE]
+====
+This procedure uses a generic approach to the Windows installation and the installation method may differ between versions of Windows. Refer to the documentation for the version of Windows that you are installing.
+====
+
+.Procedure
+
+. Start the virtual machine and connect to a graphical console.
+. Begin the Windows installation process. 
+. Select the *Advanced* installation.
+. The storage destination will not be recognised until the driver is loaded. Click `Load driver`. 
+. The drivers are attached as a SATA CD driver. Click *OK* and browse the CD drive for the storage driver to load. The drivers are arranged hierarchically according to their driver type, operating system, and CPU architecture. 
+. Repeat the previous two steps for all required drivers. 
+. Complete the Windows installation. 
+
+After Windows has been installed, you can xref:cnv-removing-virtio-disk-from-vm[remove the VirtIO driver container disk] from the virtual machine configuration file. 
+

modules/cnv_removing_virtio_disk_from_vm.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-removing-virtio-disk-from-vm]]
+= Removing the VirtIO container disk from a virtual machine
+
+After you have installed all required VirtIO drivers to the virtual machine, the `virtio-win` container disk no longer needs to be attached to the virtual machine. Remove the `virtio-win` container disk from the virtual machine configuration file. 
+
+.Procedure
+. Edit the virtual machine configuration in the web console, or edit the configuration file in your preferred editor, and remove the `disk` and the `volume`.
++
+[source,yaml]
+----
+spec:
+  domain:
+    devices:
+      disks:
+        - name: virtiocontainerdisk
+          bootOrder: 2
+          cdrom:
+            bus: sata
+volumes:
+  - containerDisk:
+      image: cnv-tech-preview/virtio-win
+    name: virtiocontainerdisk
+----
+
+. Reboot the virtual machine for the changes to take effect. 
+

modules/cnv_supported_virtio_drivers.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-supported-virtio-drivers]]
+=== Supported VirtIO drivers for Microsoft Windows virtual machines in {ProductName}
+
+.Supported drivers
+|===
+|Driver name | Hardware ID | Description
+
+|*viostor*
+|VEN_1AF4&DEV_1001 +
+VEN_1AF4&DEV_1042
+|The block driver. May represent as an *SCSI Controller* in the *Other devices* group.
+
+|*viorng*
+|VEN_1AF4&DEV_1005 +
+VEN_1AF4&DEV_1044
+|The entropy source driver. May represent as an *PCI Device* in the *Other devices* group.
+
+|*NetKVM*
+|VEN_1AF4&DEV_1000 +
+VEN_1AF4&DEV_1041
+|The network driver. May represent as an *Ethernet Controller* in the *Other devices* group. Available only if a VirtIO NIC is configured.
+|===
+
+

modules/cnv_virtio_drivers.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * cnv_users_guide/cnv_users_guide.adoc
+
+[[cnv-virtio-drivers]]
+= VirtIO drivers for Microsoft Windows virtual machines
+
+VirtIO drivers are paravirtualized device drivers required for Microsoft Windows virtual machines to run properly in {ProductName}. The xref:cnv-supported-virtio-drivers[supported drivers] are available in the `virtio-win` container disk of the Red Hat Container Catalog.
+
+The `virtio-win` container disk must be xref:cnv-adding-virtio-drivers-vm-yaml[attached to the virtual machine as a SATA CD drive] to enable driver installation. The VirtIO drivers can be installed xref:cnv-installing-virtio-drivers-installing-windows[during Windows installation on the virtual machine], or xref:cnv-installing-virtio-drivers-existing-windows[added to an existing Windows installation].
+
+After the drivers are installed, the `virtio-win` container disk can be xref:cnv-removing-virtio-disk-from-vm[removed from the virtual machine].
+