Skip to content

docs(vm): correct overcommit defaults and warn about aggressive CPU ratio #1077

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abonillabeeche wants to merge 12 commits into
base: main
Choose a base branch
from
Open

docs(vm): correct overcommit defaults and warn about aggressive CPU ratio #1077

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
3f2175f
docs(create-windows-vm): recommend virtio-scsi bus and Hyper-V enligh…
abonillabeeche Jul 10, 2026
07654f6
docs(vm): correct overcommit defaults and warn about aggressive CPU r…
abonillabeeche Jul 10, 2026
f69f777
Update docs/vm/virtual-machines.md
abonillabeeche Jul 13, 2026
723d45d
Update docs/vm/resource-overcommit.md
abonillabeeche Jul 13, 2026
f6519e2
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
d14aff3
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
d45309c
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
6743535
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
51e0735
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
1d906ce
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
c3850a1
Update docs/vm/create-windows-vm.md
abonillabeeche Jul 13, 2026
106b017
docs: drop create-windows-vm.md changes to de-duplicate with #1076
abonillabeeche Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 47 additions & 3 deletions docs/vm/create-windows-vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated
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`.
Expand All @@ -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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated
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`.
Expand All @@ -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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated
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
Expand Down Expand Up @@ -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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

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 }
```
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

Restart the VM for the changes to take effect. Verify from outside the guest:

```
kubectl get vmi <vm-name> -o json | jq '.spec.domain.features.hyperv'
```
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

## Known Issues

### Windows ISO unable to boot when using EFI mode
Expand Down
10 changes: 8 additions & 2 deletions docs/vm/resource-overcommit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,22 @@ 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

Classic memory overcommitment or memory ballooning is not yet supported by this feature. In other words, memory used by a virtual machine instance cannot be returned once allocated.

:::

:::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%.

:::
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

## 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.
Expand Down
8 changes: 7 additions & 1 deletion docs/vm/virtual-machines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
abonillabeeche marked this conversation as resolved.
Outdated

:::

## Validated Guest Operating Systems

Expand Down
50 changes: 47 additions & 3 deletions versioned_docs/version-v1.8/vm/create-windows-vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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 <vm-name> -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
Expand Down
10 changes: 8 additions & 2 deletions versioned_docs/version-v1.8/vm/resource-overcommit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,22 @@ 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

Classic memory overcommitment or memory ballooning is not yet supported by this feature. In other words, memory used by a virtual machine instance cannot be returned once allocated.

:::

:::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.
Expand Down
8 changes: 7 additions & 1 deletion versioned_docs/version-v1.8/vm/virtual-machines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down