From d57622bcbd1f5cc3dfb69ced4521ce5e4f390959 Mon Sep 17 00:00:00 2001 From: Andrew Burden Date: Fri, 8 Feb 2019 13:01:03 +1000 Subject: [PATCH] BZ#1673785 - Virtio drivers for Win VMs: concept, adding them to VM as disk, installation on fresh and existing VMs, removing disk from VM. --- cnv_users_guide/cnv_users_guide.adoc | 10 ++++++ .../cnv_adding_virtio_drivers_vm_yaml.adoc | 34 +++++++++++++++++++ ...lling_virtio_drivers_existing_windows.adoc | 34 +++++++++++++++++++ ...ing_virtio_drivers_installing_windows.adoc | 31 +++++++++++++++++ modules/cnv_removing_virtio_disk_from_vm.adoc | 30 ++++++++++++++++ modules/cnv_supported_virtio_drivers.adoc | 28 +++++++++++++++ modules/cnv_virtio_drivers.adoc | 13 +++++++ 7 files changed, 180 insertions(+) create mode 100644 modules/cnv_adding_virtio_drivers_vm_yaml.adoc create mode 100644 modules/cnv_installing_virtio_drivers_existing_windows.adoc create mode 100644 modules/cnv_installing_virtio_drivers_installing_windows.adoc create mode 100644 modules/cnv_removing_virtio_disk_from_vm.adoc create mode 100644 modules/cnv_supported_virtio_drivers.adoc create mode 100644 modules/cnv_virtio_drivers.adoc diff --git a/cnv_users_guide/cnv_users_guide.adoc b/cnv_users_guide/cnv_users_guide.adoc index 789bfc260af2..a9098e191fdc 100644 --- a/cnv_users_guide/cnv_users_guide.adoc +++ b/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,6 +111,7 @@ 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] @@ -110,3 +119,4 @@ 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] + diff --git a/modules/cnv_adding_virtio_drivers_vm_yaml.adoc b/modules/cnv_adding_virtio_drivers_vm_yaml.adoc new file mode 100644 index 000000000000..6eb89fec862a --- /dev/null +++ b/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. + diff --git a/modules/cnv_installing_virtio_drivers_existing_windows.adoc b/modules/cnv_installing_virtio_drivers_existing_windows.adoc new file mode 100644 index 000000000000..f0ca84097dcf --- /dev/null +++ b/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. + diff --git a/modules/cnv_installing_virtio_drivers_installing_windows.adoc b/modules/cnv_installing_virtio_drivers_installing_windows.adoc new file mode 100644 index 000000000000..084191346969 --- /dev/null +++ b/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. + diff --git a/modules/cnv_removing_virtio_disk_from_vm.adoc b/modules/cnv_removing_virtio_disk_from_vm.adoc new file mode 100644 index 000000000000..55418b4b7cab --- /dev/null +++ b/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. + diff --git a/modules/cnv_supported_virtio_drivers.adoc b/modules/cnv_supported_virtio_drivers.adoc new file mode 100644 index 000000000000..065c657fdc26 --- /dev/null +++ b/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. +|=== + + diff --git a/modules/cnv_virtio_drivers.adoc b/modules/cnv_virtio_drivers.adoc new file mode 100644 index 000000000000..d5d0c75585fd --- /dev/null +++ b/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]. +