From 3f2175fe80044f03498c3da1c96b1b6d770874ff Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Thu, 9 Jul 2026 20:47:19 -0400 Subject: [PATCH 01/11] docs(create-windows-vm): recommend virtio-scsi bus and Hyper-V enlightenments Update the Volumes tab guidance to recommend the SCSI bus (virtio-scsi) for Windows workloads that do sustained writes; virtio-scsi supports multiple queues and has a more efficient DISCARD path than virtio-blk. Clarify that the Cloud Config field is processed on Windows images that include Cloudbase-Init (rather than being ignored outright). Note that after VMDP is installed the network model can be switched from e1000 to virtio for better throughput. Add a new "Recommended Tuning" section documenting KubeVirt's Hyper-V TLFS enlightenments as a suggested performance tuning for Windows guests, with the full YAML block and a verification command. Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 50 +++++++++++++++++-- .../version-v1.8/vm/create-windows-vm.md | 50 +++++++++++++++++-- 2 files changed, 94 insertions(+), 6 deletions(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index d5b635cbc7..87bd9afcb8 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -68,7 +68,7 @@ The `bootOrder` values need to be set with the installation image first. If you 2. `Type`: Select `disk`. 3. `StorageClass`: You can use the default StorageClass `harvester-longhorn` or specify a custom one. 4. `Size`: The value `32` is set by default. See the disk space requirements for [Windows Server](https://docs.microsoft.com/en-us/windows-server/get-started/hardware-requirements#storage-controller-and-disk-space-requirements) and [Windows 11](https://docs.microsoft.com/en-us/windows/whats-new/windows-11-requirements#hardware-requirements) before changing this value. - 5. `Bus`: The value `VirtIO` is set by default. You can keep it or change it to the other available options, `SATA` or `SCSI`. + 5. `Bus`: The value `VirtIO` is set by default. For Windows workloads that generate sustained writes (for example large file copies, database write-ahead logs, or backup targets), `SCSI` (virtio-scsi) generally performs better than `VirtIO` (virtio-blk) — it supports multiple queues and has a more efficient DISCARD path. `SATA` is a compatible fallback for scenarios that cannot load paravirtualized drivers at boot time. 3. The **third volume** is a `Container` with the following values: 1. `Name`: The value `virtio-container-disk` is set by default. You can keep it or change it. 2. `Type`: Select `cd-rom`. @@ -82,7 +82,7 @@ The `bootOrder` values need to be set with the installation image first. If you 1. The **Management Network** is added by default with the following values: 1. `Name`: The value `default` is set by default. You can keep it or change it. - 2. `Model`: The value `e1000` is set by default. You can keep it or change it to the other available options from the dropdown. + 2. `Model`: The value `e1000` is set by default so the guest can obtain network connectivity before paravirtualized drivers are installed. Once VMDP (or virtio-win drivers) is loaded inside the guest, switching to `virtio` provides higher throughput and lower CPU overhead for sustained network transfers. 3. `Network`: The value `management Network` is set by default. You can't change this option if no other network has been created. See [Harvester Network](../networking/harvester-network.md) for the full description on how to create new networks. 4. `Type`: The value `masquerade` is set by default. You can keep it or change it to the other available option, `bridge`. 2. You can add additional networks by clicking `Add Network`. @@ -106,7 +106,7 @@ Changing the `Node Scheduling` settings can impact Harvester features, such as d 1. `OS Type`: The value `Windows` is set by default. It's recommended you don't change it. 2. `Machine Type`: The value `None` is set by default. It's recommended you don't change it. See the [KubeVirt Machine Type](https://kubevirt.io/user-guide/virtual_machines/virtual_hardware/#machine-type) documentation before you change this value. 3. (Optional) `Hostname`: Set the VM hostname. -4. (Optional) `Cloud Config`: Both `User Data` and `Network Data` values are set with default values. Currently, these configurations are not applied to Windows-based VMs. +4. (Optional) `Cloud Config`: Both `User Data` and `Network Data` values are set with default values. If the selected Windows image ships with [Cloudbase-Init](https://cloudbase.it/cloudbase-init/) (a common addition to modern Windows images), the `User Data` is processed at first boot and can inject per-VM configuration — SSH keys, local administrator accounts, VMDP install commands, hostname, first-boot PowerShell scripts, and so on. If the image does not include Cloudbase-Init, the `User Data` is still stored on the noCloud drive but nothing inside the guest will consume it. 5. (Optional) `Enable TPM`, `Booting in EFI mode`, `Secure Boot`: Both the TPM 2.0 device and UEFI firmware with Secure Boot are hard requirements for Windows 11. :::note @@ -173,6 +173,50 @@ For full instructions on how to install the VMDP guest driver and tools see the ::: +## Recommended Tuning + +### Enable Hyper-V Enlightenments + +Windows guests benefit substantially from KubeVirt's Hyper-V TLFS (Top-Level Functional Specification) enlightenment set — paravirtualized interrupt delivery (SynIC), the Hyper-V synthetic timer with direct interrupts, TLB flush hypercalls, VAPIC, and the Hyper-V clock timer. Enabling them typically: + +- Reduces first-touch write allocation time on thin-provisioned storage. +- Smooths out sustained-write throughput and reduces periodic stalls during large file copies. +- Lowers per-interrupt scheduling overhead inside the guest. + +The enlightenments are not enabled by default in the VM creation form. To apply them, click **Edit as YAML** in the VM edit view and add the following to `.spec.template.spec.domain`: + +```yaml +features: + acpi: { enabled: true } + apic: { enabled: true } + smm: { enabled: true } + hyperv: + relaxed: { enabled: true } + vapic: { enabled: true } + spinlocks: { enabled: true, spinlocks: 8191 } + vpindex: { enabled: true } + synic: { enabled: true } + synictimer: { enabled: true } + ipi: { enabled: true } + runtime: { enabled: true } + reset: { enabled: true } +clock: + utc: {} + timer: + hpet: { present: false } + hyperv: { present: true } + pit: { tickPolicy: delay } + rtc: { tickPolicy: catchup } +``` + +Restart the VM for the changes to take effect. Verify from outside the guest: + +``` +kubectl get vmi -o json | jq '.spec.domain.features.hyperv' +``` + +The set above matches the "balanced set for performance and stability" recommended in the SUSE Support KB article [_Lower disk I/O performance in Windows 11 VMs compared to Linux guests on Harvester_](https://support.scc.suse.com/s/kb/Lower-disk-I-O-performance-in-Windows-11-VMs-compared-to-Linux-guests-on-Harvester). More aggressive enlightenments (`tlbflush`, `frequencies`, `reenlightenment`, or `synictimer` with `direct: true`) can be enabled per-VM when the cluster hardware supports them, but they may affect live-migration compatibility across nodes with different CPU generations — see the [KubeVirt Hyper-V enlightenments documentation](https://kubevirt.io/user-guide/compute/hyperv/) and the [SUSE Virtualization blog on tuning Windows VM performance](https://www.suse.com/c/tuning-windows-vm-performance-on-suse-virtualization/) for details. + ## Known Issues ### Windows ISO unable to boot when using EFI mode diff --git a/versioned_docs/version-v1.8/vm/create-windows-vm.md b/versioned_docs/version-v1.8/vm/create-windows-vm.md index d5b635cbc7..87bd9afcb8 100644 --- a/versioned_docs/version-v1.8/vm/create-windows-vm.md +++ b/versioned_docs/version-v1.8/vm/create-windows-vm.md @@ -68,7 +68,7 @@ The `bootOrder` values need to be set with the installation image first. If you 2. `Type`: Select `disk`. 3. `StorageClass`: You can use the default StorageClass `harvester-longhorn` or specify a custom one. 4. `Size`: The value `32` is set by default. See the disk space requirements for [Windows Server](https://docs.microsoft.com/en-us/windows-server/get-started/hardware-requirements#storage-controller-and-disk-space-requirements) and [Windows 11](https://docs.microsoft.com/en-us/windows/whats-new/windows-11-requirements#hardware-requirements) before changing this value. - 5. `Bus`: The value `VirtIO` is set by default. You can keep it or change it to the other available options, `SATA` or `SCSI`. + 5. `Bus`: The value `VirtIO` is set by default. For Windows workloads that generate sustained writes (for example large file copies, database write-ahead logs, or backup targets), `SCSI` (virtio-scsi) generally performs better than `VirtIO` (virtio-blk) — it supports multiple queues and has a more efficient DISCARD path. `SATA` is a compatible fallback for scenarios that cannot load paravirtualized drivers at boot time. 3. The **third volume** is a `Container` with the following values: 1. `Name`: The value `virtio-container-disk` is set by default. You can keep it or change it. 2. `Type`: Select `cd-rom`. @@ -82,7 +82,7 @@ The `bootOrder` values need to be set with the installation image first. If you 1. The **Management Network** is added by default with the following values: 1. `Name`: The value `default` is set by default. You can keep it or change it. - 2. `Model`: The value `e1000` is set by default. You can keep it or change it to the other available options from the dropdown. + 2. `Model`: The value `e1000` is set by default so the guest can obtain network connectivity before paravirtualized drivers are installed. Once VMDP (or virtio-win drivers) is loaded inside the guest, switching to `virtio` provides higher throughput and lower CPU overhead for sustained network transfers. 3. `Network`: The value `management Network` is set by default. You can't change this option if no other network has been created. See [Harvester Network](../networking/harvester-network.md) for the full description on how to create new networks. 4. `Type`: The value `masquerade` is set by default. You can keep it or change it to the other available option, `bridge`. 2. You can add additional networks by clicking `Add Network`. @@ -106,7 +106,7 @@ Changing the `Node Scheduling` settings can impact Harvester features, such as d 1. `OS Type`: The value `Windows` is set by default. It's recommended you don't change it. 2. `Machine Type`: The value `None` is set by default. It's recommended you don't change it. See the [KubeVirt Machine Type](https://kubevirt.io/user-guide/virtual_machines/virtual_hardware/#machine-type) documentation before you change this value. 3. (Optional) `Hostname`: Set the VM hostname. -4. (Optional) `Cloud Config`: Both `User Data` and `Network Data` values are set with default values. Currently, these configurations are not applied to Windows-based VMs. +4. (Optional) `Cloud Config`: Both `User Data` and `Network Data` values are set with default values. If the selected Windows image ships with [Cloudbase-Init](https://cloudbase.it/cloudbase-init/) (a common addition to modern Windows images), the `User Data` is processed at first boot and can inject per-VM configuration — SSH keys, local administrator accounts, VMDP install commands, hostname, first-boot PowerShell scripts, and so on. If the image does not include Cloudbase-Init, the `User Data` is still stored on the noCloud drive but nothing inside the guest will consume it. 5. (Optional) `Enable TPM`, `Booting in EFI mode`, `Secure Boot`: Both the TPM 2.0 device and UEFI firmware with Secure Boot are hard requirements for Windows 11. :::note @@ -173,6 +173,50 @@ For full instructions on how to install the VMDP guest driver and tools see the ::: +## Recommended Tuning + +### Enable Hyper-V Enlightenments + +Windows guests benefit substantially from KubeVirt's Hyper-V TLFS (Top-Level Functional Specification) enlightenment set — paravirtualized interrupt delivery (SynIC), the Hyper-V synthetic timer with direct interrupts, TLB flush hypercalls, VAPIC, and the Hyper-V clock timer. Enabling them typically: + +- Reduces first-touch write allocation time on thin-provisioned storage. +- Smooths out sustained-write throughput and reduces periodic stalls during large file copies. +- Lowers per-interrupt scheduling overhead inside the guest. + +The enlightenments are not enabled by default in the VM creation form. To apply them, click **Edit as YAML** in the VM edit view and add the following to `.spec.template.spec.domain`: + +```yaml +features: + acpi: { enabled: true } + apic: { enabled: true } + smm: { enabled: true } + hyperv: + relaxed: { enabled: true } + vapic: { enabled: true } + spinlocks: { enabled: true, spinlocks: 8191 } + vpindex: { enabled: true } + synic: { enabled: true } + synictimer: { enabled: true } + ipi: { enabled: true } + runtime: { enabled: true } + reset: { enabled: true } +clock: + utc: {} + timer: + hpet: { present: false } + hyperv: { present: true } + pit: { tickPolicy: delay } + rtc: { tickPolicy: catchup } +``` + +Restart the VM for the changes to take effect. Verify from outside the guest: + +``` +kubectl get vmi -o json | jq '.spec.domain.features.hyperv' +``` + +The set above matches the "balanced set for performance and stability" recommended in the SUSE Support KB article [_Lower disk I/O performance in Windows 11 VMs compared to Linux guests on Harvester_](https://support.scc.suse.com/s/kb/Lower-disk-I-O-performance-in-Windows-11-VMs-compared-to-Linux-guests-on-Harvester). More aggressive enlightenments (`tlbflush`, `frequencies`, `reenlightenment`, or `synictimer` with `direct: true`) can be enabled per-VM when the cluster hardware supports them, but they may affect live-migration compatibility across nodes with different CPU generations — see the [KubeVirt Hyper-V enlightenments documentation](https://kubevirt.io/user-guide/compute/hyperv/) and the [SUSE Virtualization blog on tuning Windows VM performance](https://www.suse.com/c/tuning-windows-vm-performance-on-suse-virtualization/) for details. + ## Known Issues ### Windows ISO unable to boot when using EFI mode From 07654f6d36475028543d70cae2d5654c4b8d21c0 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Thu, 9 Jul 2026 21:20:12 -0400 Subject: [PATCH 02/11] docs(vm): correct overcommit defaults and warn about aggressive CPU ratio Updates the Resource Overcommit page to reflect the current defaults shipped in Harvester v1.8+: - CPU allocation ratio: 1600% -> 1000% - Storage allocation ratio: 200% -> 100% Adds a note that the default CPU allocation ratio of 1000% is aggressive and can produce noticeable CPU steal and latency spikes in guests. Encourages benchmarking vCPUs for latency-sensitive or sustained CPU-bound workloads and suggests a conservative starting point of 200-400%. Also adds a note on the Virtual Machines landing page pointing users at the Resource Overcommit page before creating VMs so that the allocation ratios can be reviewed against workload requirements. Signed-off-by: Alejandro Bonilla --- docs/vm/resource-overcommit.md | 10 ++++++++-- docs/vm/virtual-machines.md | 8 +++++++- versioned_docs/version-v1.8/vm/resource-overcommit.md | 10 ++++++++-- versioned_docs/version-v1.8/vm/virtual-machines.md | 8 +++++++- 4 files changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/vm/resource-overcommit.md b/docs/vm/resource-overcommit.md index d2ee1d540b..c683acbcc7 100644 --- a/docs/vm/resource-overcommit.md +++ b/docs/vm/resource-overcommit.md @@ -18,9 +18,9 @@ Harvester supports global configuration of resource overload percentages on CPU, Harvester allows you to overcommit CPU and RAM on compute nodes. This allows you to increase the number of instances running on your cloud at the cost of reducing the performance of the instances. The Compute service uses the following ratios by default: -- CPU allocation ratio: 1600% +- CPU allocation ratio: 1000% - RAM allocation ratio: 150% -- Storage allocation ratio: 200% +- Storage allocation ratio: 100% :::note @@ -28,6 +28,12 @@ Classic memory overcommitment or memory ballooning is not yet supported by this ::: +:::note + +The default CPU allocation ratio of 1000% is aggressive: a host CPU is treated as if it provides 10 vCPUs. Under load, this can produce noticeable CPU steal and latency spikes in guests. For workloads that are latency-sensitive or perform sustained CPU-bound work (for example, databases, real-time services, or interactive Windows desktops), benchmark with a representative workload and reduce the CPU allocation ratio if you observe degradation. A common conservative starting point is 200–400%. + +::: + ## Configure the global setting [`overcommit-config`](../advanced/settings.md#overcommit-config) Users can modify the global `overcommit-config` by following the steps below, and it will be applied to each newly created virtual machine after the change. diff --git a/docs/vm/virtual-machines.md b/docs/vm/virtual-machines.md index edf6e06dcc..46d8ea4d79 100644 --- a/docs/vm/virtual-machines.md +++ b/docs/vm/virtual-machines.md @@ -20,7 +20,13 @@ You can create [Linux VMs](../vm/create-vm.md) using one of the following method - Kubernetes API: Create a `VirtualMachine` object. - [Harvester Terraform Provider](../terraform/terraform-provider.md): Define a `harvester_virtualmachine` resource block. -Creating [Windows VMs](../vm/create-windows-vm.md) on the Harvester UI involves slightly different steps. Harvester provides a VM template named `windows-iso-image-base-template` that adds a volume with the Virtio drivers for Windows, which streamlines the VM configuration process. If you require Virtio devices but choose to not use the template, you must add your own Virtio drivers for Windows to enable correct hardware detection. +Creating [Windows VMs](../vm/create-windows-vm.md) on the Harvester UI involves slightly different steps. Harvester provides a VM template named `windows-iso-image-base-template` that adds a volume with the Virtio drivers for Windows, which streamlines the VM configuration process. If you require Virtio devices but choose to not use the template, you must add your own Virtio drivers for Windows to enable correct hardware detection. + +:::note + +Before creating virtual machines, review [Resource Overcommit](../vm/resource-overcommit.md) to confirm that the cluster's default CPU, memory, and storage allocation ratios match your workload requirements. The defaults suit dense general-purpose workloads but may be too aggressive for latency-sensitive or CPU-bound guests. + +::: ## Validated Guest Operating Systems diff --git a/versioned_docs/version-v1.8/vm/resource-overcommit.md b/versioned_docs/version-v1.8/vm/resource-overcommit.md index d2ee1d540b..c683acbcc7 100644 --- a/versioned_docs/version-v1.8/vm/resource-overcommit.md +++ b/versioned_docs/version-v1.8/vm/resource-overcommit.md @@ -18,9 +18,9 @@ Harvester supports global configuration of resource overload percentages on CPU, Harvester allows you to overcommit CPU and RAM on compute nodes. This allows you to increase the number of instances running on your cloud at the cost of reducing the performance of the instances. The Compute service uses the following ratios by default: -- CPU allocation ratio: 1600% +- CPU allocation ratio: 1000% - RAM allocation ratio: 150% -- Storage allocation ratio: 200% +- Storage allocation ratio: 100% :::note @@ -28,6 +28,12 @@ Classic memory overcommitment or memory ballooning is not yet supported by this ::: +:::note + +The default CPU allocation ratio of 1000% is aggressive: a host CPU is treated as if it provides 10 vCPUs. Under load, this can produce noticeable CPU steal and latency spikes in guests. For workloads that are latency-sensitive or perform sustained CPU-bound work (for example, databases, real-time services, or interactive Windows desktops), benchmark with a representative workload and reduce the CPU allocation ratio if you observe degradation. A common conservative starting point is 200–400%. + +::: + ## Configure the global setting [`overcommit-config`](../advanced/settings.md#overcommit-config) Users can modify the global `overcommit-config` by following the steps below, and it will be applied to each newly created virtual machine after the change. diff --git a/versioned_docs/version-v1.8/vm/virtual-machines.md b/versioned_docs/version-v1.8/vm/virtual-machines.md index edf6e06dcc..46d8ea4d79 100644 --- a/versioned_docs/version-v1.8/vm/virtual-machines.md +++ b/versioned_docs/version-v1.8/vm/virtual-machines.md @@ -20,7 +20,13 @@ You can create [Linux VMs](../vm/create-vm.md) using one of the following method - Kubernetes API: Create a `VirtualMachine` object. - [Harvester Terraform Provider](../terraform/terraform-provider.md): Define a `harvester_virtualmachine` resource block. -Creating [Windows VMs](../vm/create-windows-vm.md) on the Harvester UI involves slightly different steps. Harvester provides a VM template named `windows-iso-image-base-template` that adds a volume with the Virtio drivers for Windows, which streamlines the VM configuration process. If you require Virtio devices but choose to not use the template, you must add your own Virtio drivers for Windows to enable correct hardware detection. +Creating [Windows VMs](../vm/create-windows-vm.md) on the Harvester UI involves slightly different steps. Harvester provides a VM template named `windows-iso-image-base-template` that adds a volume with the Virtio drivers for Windows, which streamlines the VM configuration process. If you require Virtio devices but choose to not use the template, you must add your own Virtio drivers for Windows to enable correct hardware detection. + +:::note + +Before creating virtual machines, review [Resource Overcommit](../vm/resource-overcommit.md) to confirm that the cluster's default CPU, memory, and storage allocation ratios match your workload requirements. The defaults suit dense general-purpose workloads but may be too aggressive for latency-sensitive or CPU-bound guests. + +::: ## Validated Guest Operating Systems From f69f777da81257a4067be0cb650b5bdff0d74951 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:41:46 -0400 Subject: [PATCH 03/11] Update docs/vm/virtual-machines.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/virtual-machines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vm/virtual-machines.md b/docs/vm/virtual-machines.md index 46d8ea4d79..923d8852f0 100644 --- a/docs/vm/virtual-machines.md +++ b/docs/vm/virtual-machines.md @@ -24,7 +24,7 @@ Creating [Windows VMs](../vm/create-windows-vm.md) on the Harvester UI involves :::note -Before creating virtual machines, review [Resource Overcommit](../vm/resource-overcommit.md) to confirm that the cluster's default CPU, memory, and storage allocation ratios match your workload requirements. The defaults suit dense general-purpose workloads but may be too aggressive for latency-sensitive or CPU-bound guests. +Before creating virtual machines, review [Resource Overcommit](../vm/resource-overcommit.md) and verify that the cluster's default CPU, memory, and storage allocation ratios match your workload requirements. The default values suit dense, general-purpose workloads but may be too aggressive for latency-sensitive or CPU-bound guests. ::: From 723d45d571e915ec4e4f691e8627793c73be204b Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:42:09 -0400 Subject: [PATCH 04/11] Update docs/vm/resource-overcommit.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/resource-overcommit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vm/resource-overcommit.md b/docs/vm/resource-overcommit.md index c683acbcc7..d4da713bb4 100644 --- a/docs/vm/resource-overcommit.md +++ b/docs/vm/resource-overcommit.md @@ -28,9 +28,9 @@ Classic memory overcommitment or memory ballooning is not yet supported by this ::: -:::note +:::info important -The default CPU allocation ratio of 1000% is aggressive: a host CPU is treated as if it provides 10 vCPUs. Under load, this can produce noticeable CPU steal and latency spikes in guests. For workloads that are latency-sensitive or perform sustained CPU-bound work (for example, databases, real-time services, or interactive Windows desktops), benchmark with a representative workload and reduce the CPU allocation ratio if you observe degradation. A common conservative starting point is 200–400%. +The default CPU allocation ratio of 1000% is aggressive, treating each host CPU as 10 vCPUs. Under heavy workloads, this ratio can cause significant CPU steal time and performance degradation. Consider lowering this ratio for latency-sensitive or sustained CPU-bound workloads (such as databases, real-time services, and interactive Windows desktops). A conservative starting point is 200 to 400% based on benchmarking results under realistic loads. ::: From f6519e286ad9cef0b63417cdf6341d42498cc097 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:42:28 -0400 Subject: [PATCH 05/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 87bd9afcb8..669f8e339e 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -106,7 +106,7 @@ Changing the `Node Scheduling` settings can impact Harvester features, such as d 1. `OS Type`: The value `Windows` is set by default. It's recommended you don't change it. 2. `Machine Type`: The value `None` is set by default. It's recommended you don't change it. See the [KubeVirt Machine Type](https://kubevirt.io/user-guide/virtual_machines/virtual_hardware/#machine-type) documentation before you change this value. 3. (Optional) `Hostname`: Set the VM hostname. -4. (Optional) `Cloud Config`: Both `User Data` and `Network Data` values are set with default values. If the selected Windows image ships with [Cloudbase-Init](https://cloudbase.it/cloudbase-init/) (a common addition to modern Windows images), the `User Data` is processed at first boot and can inject per-VM configuration — SSH keys, local administrator accounts, VMDP install commands, hostname, first-boot PowerShell scripts, and so on. If the image does not include Cloudbase-Init, the `User Data` is still stored on the noCloud drive but nothing inside the guest will consume it. +4. `Cloud Config` (Optional): The values for both `User Data` and `Network Data` are set by default. If the selected Windows image includes [Cloudbase-Init](https://cloudbase.it/cloudbase-init/) (a common addition to automated Windows cloud images), the guest processes the `User Data` during its initial boot phase. This allows injection of custom configurations (such as SSH keys, local administrator accounts, driver installation commands, custom hostnames, and first-boot PowerShell scripts) for each virtual machine. If the image does not include Cloudbase-Init, the system still mounts the `User Data` on the configuration drive (`NoCloud` ISO format), but the guest operating system ignores it. 5. (Optional) `Enable TPM`, `Booting in EFI mode`, `Secure Boot`: Both the TPM 2.0 device and UEFI firmware with Secure Boot are hard requirements for Windows 11. :::note From d14aff3e4668ab1c16bdb5afb35f3d452d2aebe5 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:42:58 -0400 Subject: [PATCH 06/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 669f8e339e..60c2db6c6f 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -68,7 +68,7 @@ The `bootOrder` values need to be set with the installation image first. If you 2. `Type`: Select `disk`. 3. `StorageClass`: You can use the default StorageClass `harvester-longhorn` or specify a custom one. 4. `Size`: The value `32` is set by default. See the disk space requirements for [Windows Server](https://docs.microsoft.com/en-us/windows-server/get-started/hardware-requirements#storage-controller-and-disk-space-requirements) and [Windows 11](https://docs.microsoft.com/en-us/windows/whats-new/windows-11-requirements#hardware-requirements) before changing this value. - 5. `Bus`: The value `VirtIO` is set by default. For Windows workloads that generate sustained writes (for example large file copies, database write-ahead logs, or backup targets), `SCSI` (virtio-scsi) generally performs better than `VirtIO` (virtio-blk) — it supports multiple queues and has a more efficient DISCARD path. `SATA` is a compatible fallback for scenarios that cannot load paravirtualized drivers at boot time. + 5. `Bus`: The default value is `VirtIO`. For Windows workloads that generate sustained writes (such as large file copies, database write-ahead logs, and backup targets), `SCSI` (`virtio-scsi`) generally outperforms `VirtIO` (`virtio-blk`) because it supports multiple queues and uses a more efficient `DISCARD` path. `SATA` is a secondary option for scenarios where paravirtualized drivers cannot be loaded at boot time. 3. The **third volume** is a `Container` with the following values: 1. `Name`: The value `virtio-container-disk` is set by default. You can keep it or change it. 2. `Type`: Select `cd-rom`. From d45309c5094ea3ba0696f60dc4cadc0681d22dc8 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:43:09 -0400 Subject: [PATCH 07/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 60c2db6c6f..7959f3e294 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -177,11 +177,11 @@ For full instructions on how to install the VMDP guest driver and tools see the ### Enable Hyper-V Enlightenments -Windows guests benefit substantially from KubeVirt's Hyper-V TLFS (Top-Level Functional Specification) enlightenment set — paravirtualized interrupt delivery (SynIC), the Hyper-V synthetic timer with direct interrupts, TLB flush hypercalls, VAPIC, and the Hyper-V clock timer. Enabling them typically: +Windows guests benefit significantly from KubeVirt's Hyper-V Top-Level Functional Specification (TLFS) enlightenment features. These include paravirtualized interrupt delivery (SynIC), the Hyper-V synthetic timer with direct interrupts, TLB flush hypercalls, VAPIC, and the Hyper-V clock timer. Enabling these features typically results in the following: -- Reduces first-touch write allocation time on thin-provisioned storage. -- Smooths out sustained-write throughput and reduces periodic stalls during large file copies. -- Lowers per-interrupt scheduling overhead inside the guest. +- Reduced initial write allocation time on thin-provisioned storage. +- Stable throughput during sustained write operations and minimal periodic stalls during large file copies. +- Lower per-interrupt scheduling overhead within the guest operating system. The enlightenments are not enabled by default in the VM creation form. To apply them, click **Edit as YAML** in the VM edit view and add the following to `.spec.template.spec.domain`: From 6743535e147d406e97acddfdfeba9635135beb71 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:43:33 -0400 Subject: [PATCH 08/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 56 ++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 7959f3e294..a07e438ab2 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -183,31 +183,37 @@ Windows guests benefit significantly from KubeVirt's Hyper-V Top-Level Functiona - Stable throughput during sustained write operations and minimal periodic stalls during large file copies. - Lower per-interrupt scheduling overhead within the guest operating system. -The enlightenments are not enabled by default in the VM creation form. To apply them, click **Edit as YAML** in the VM edit view and add the following to `.spec.template.spec.domain`: - -```yaml -features: - acpi: { enabled: true } - apic: { enabled: true } - smm: { enabled: true } - hyperv: - relaxed: { enabled: true } - vapic: { enabled: true } - spinlocks: { enabled: true, spinlocks: 8191 } - vpindex: { enabled: true } - synic: { enabled: true } - synictimer: { enabled: true } - ipi: { enabled: true } - runtime: { enabled: true } - reset: { enabled: true } -clock: - utc: {} - timer: - hpet: { present: false } - hyperv: { present: true } - pit: { tickPolicy: delay } - rtc: { tickPolicy: catchup } -``` +The enlightenments are _not_ enabled by default. To enable them, perform the following steps: + +1. On the Harvester UI, go to **Virtual Machines**. + +1. Locate the target virtual machine, and then select **⋮ > Edit as YAML**. + +1. Add the following block to `.spec.template.spec.domain`: + + ```yaml + features: + acpi: { enabled: true } + apic: { enabled: true } + smm: { enabled: true } + hyperv: + relaxed: { enabled: true } + vapic: { enabled: true } + spinlocks: { enabled: true, spinlocks: 8191 } + vpindex: { enabled: true } + synic: { enabled: true } + synictimer: { enabled: true } + ipi: { enabled: true } + runtime: { enabled: true } + reset: { enabled: true } + clock: + utc: {} + timer: + hpet: { present: false } + hyperv: { present: true } + pit: { tickPolicy: delay } + rtc: { tickPolicy: catchup } + ``` Restart the VM for the changes to take effect. Verify from outside the guest: From 51e0735e564a7fdfab3f566ca4e5279b66358cb8 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:43:49 -0400 Subject: [PATCH 09/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index a07e438ab2..225eeddc9c 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -82,7 +82,7 @@ The `bootOrder` values need to be set with the installation image first. If you 1. The **Management Network** is added by default with the following values: 1. `Name`: The value `default` is set by default. You can keep it or change it. - 2. `Model`: The value `e1000` is set by default so the guest can obtain network connectivity before paravirtualized drivers are installed. Once VMDP (or virtio-win drivers) is loaded inside the guest, switching to `virtio` provides higher throughput and lower CPU overhead for sustained network transfers. + 2. `Model`: The default value is `e1000`. This option ensures the guest operating system can obtain network connectivity before paravirtualized drivers are installed. Once VMDP (or VirtIO drivers such as `virtio-win`) is loaded inside the guest, switching to `virtio` provides higher throughput and lower CPU overhead for sustained network transfers. 3. `Network`: The value `management Network` is set by default. You can't change this option if no other network has been created. See [Harvester Network](../networking/harvester-network.md) for the full description on how to create new networks. 4. `Type`: The value `masquerade` is set by default. You can keep it or change it to the other available option, `bridge`. 2. You can add additional networks by clicking `Add Network`. From 1d906ce433002e4470224130acfe7fb67d5af00b Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:43:57 -0400 Subject: [PATCH 10/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 225eeddc9c..9faf79a98e 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -221,7 +221,14 @@ Restart the VM for the changes to take effect. Verify from outside the guest: kubectl get vmi -o json | jq '.spec.domain.features.hyperv' ``` -The set above matches the "balanced set for performance and stability" recommended in the SUSE Support KB article [_Lower disk I/O performance in Windows 11 VMs compared to Linux guests on Harvester_](https://support.scc.suse.com/s/kb/Lower-disk-I-O-performance-in-Windows-11-VMs-compared-to-Linux-guests-on-Harvester). More aggressive enlightenments (`tlbflush`, `frequencies`, `reenlightenment`, or `synictimer` with `direct: true`) can be enabled per-VM when the cluster hardware supports them, but they may affect live-migration compatibility across nodes with different CPU generations — see the [KubeVirt Hyper-V enlightenments documentation](https://kubevirt.io/user-guide/compute/hyperv/) and the [SUSE Virtualization blog on tuning Windows VM performance](https://www.suse.com/c/tuning-windows-vm-performance-on-suse-virtualization/) for details. +The configuration above matches the recommendation for "best balance between performance and stability" in the SUSE Support Knowledge Base article [Lower disk I/O performance in Windows 11 VMs compared to Linux guests on Harvester](https://support.scc.suse.com/s/kb/Lower-disk-I-O-performance-in-Windows-11-VMs-compared-to-Linux-guests-on-Harvester). + +You can enable more aggressive enlightenments (such as `tlbflush`, `frequencies`, `reenlightenment`, or `synictimer` with `direct: true`) on individual virtual machines to improve their performance. However, these enlightenments have the following disadvantages: + +- Require explicit support from the underlying cluster hardware. +- Can affect live-migration compatibility across cluster nodes that run on different CPU generations. + +For more information, see [HyperV optimizations](https://kubevirt.io/user-guide/user_workloads/guest_operating_system_information/#hyperv-optimizations) in the KubeVirt documentation and [Tuning Windows VM Performance on SUSE Virtualization](https://www.suse.com/c/tuning-windows-vm-performance-on-suse-virtualization/) in the SUSE blog. ## Known Issues From c3850a1fdefd3e24613b6c1572e9648ce6530b96 Mon Sep 17 00:00:00 2001 From: Alejandro Bonilla Date: Mon, 13 Jul 2026 10:44:05 -0400 Subject: [PATCH 11/11] Update docs/vm/create-windows-vm.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Alejandro Bonilla --- docs/vm/create-windows-vm.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/vm/create-windows-vm.md b/docs/vm/create-windows-vm.md index 9faf79a98e..9b4e8d9684 100644 --- a/docs/vm/create-windows-vm.md +++ b/docs/vm/create-windows-vm.md @@ -215,11 +215,13 @@ The enlightenments are _not_ enabled by default. To enable them, perform the fol rtc: { tickPolicy: catchup } ``` -Restart the VM for the changes to take effect. Verify from outside the guest: +1. Restart the virtual machine to apply the changes. -``` -kubectl get vmi -o json | jq '.spec.domain.features.hyperv' -``` +1. Verify that the enlightenments are active from the cluster level. + + ``` + kubectl get vmi -o json | jq '.spec.domain.features.hyperv' + ``` The configuration above matches the recommendation for "best balance between performance and stability" in the SUSE Support Knowledge Base article [Lower disk I/O performance in Windows 11 VMs compared to Linux guests on Harvester](https://support.scc.suse.com/s/kb/Lower-disk-I-O-performance-in-Windows-11-VMs-compared-to-Linux-guests-on-Harvester).