Skip to content

Add best practices for PV-SCSI controller configuration #2040

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
steled wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add best practices for PV-SCSI controller configuration #2040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
859c826
Enhance vSphere documentation for disk performance
steled Nov 27, 2025
bb38d62
Add best practices for PV-SCSI controller configuration
steled Nov 27, 2025
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
16 changes: 16 additions & 0 deletions content/kubermatic/main/architecture/supported-providers/vsphere/_index.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,22 @@ When creating worker nodes for a user cluster, the user can specify an existing
Modifications like network, disk size, etc. must be done in the ova template before creating a worker node from it.
If user clusters have dedicated networks, all user clusters therefore need a custom template.

#### Improving Disk Performance with Multiple PV-SCSI Controllers

For better I/O performance in vSphere environments, it is recommended to configure your worker node template with multiple **Paravirtual SCSI (PV-SCSI) controllers**.
This allows the vSphere CSI driver to distribute additional datastores across different controllers, reducing contention and improving throughput.

##### Steps

1. When creating the VM template, add **3 additional PV-SCSI controllers** (in addition to the default one).
2. Ensure all controllers are set to **Paravirtual** mode.
3. Assign the boot disk to the first controller; CSI-provisioned volumes will automatically use the others.

##### References

- GitHub Issue: [Is it safe to use VMs configured with multiple SCSI controllers?](https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/633)
- VMware KB: [VMware recommends implementing multiple SCSI controllers](https://knowledge.broadcom.com/external/article/392848/vms-with-multiple-vmdks-report-high-disk.html#:~:text=VMware%20recommends%20implementing%20multiple%20SCSI%20controllers)

## VM Folder

During creation of a user cluster Kubermatic Kubernetes Platform (KKP) creates a dedicated VM folder in the root path on the Datastore (Defined in the [seed cluster `spec.datacenters.EXAMPLEDC.vsphere.datastore`]({{< ref "../../../tutorials-howtos/project-and-cluster-management/seed-cluster" >}})).
Expand Down
17 changes: 17 additions & 0 deletions content/machine-controller/main/cloud-providers/vsphere/template-vm/_index.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,23 @@ system, plus guides that go into more detail for specific OS.

Guides for other operating systems will be added in the future.

## Best Practice: Add Multiple PV-SCSI Controllers

To improve disk performance and optimize CSI volume placement, configure your template VM with multiple **Paravirtual SCSI controllers** before converting it to a template.

### Recommended Configuration

- Add **3 additional PV-SCSI controllers** (total: 4).
- Set all controllers to **Paravirtual** mode.
- Boot disk should remain on the first controller; additional CSI volumes will automatically use the others.

This configuration helps distribute I/O load across multiple controllers, which is especially beneficial for workloads with high disk activity.

### References

- GitHub Issue: [Is it safe to use VMs configured with multiple SCSI controllers?](https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/633)
- VMware KB: [VMware recommends implementing multiple SCSI controllers](https://knowledge.broadcom.com/external/article/392848/vms-with-multiple-vmdks-report-high-disk.html#:~:text=VMware%20recommends%20implementing%20multiple%20SCSI%20controllers)

{{% notice warning %}}
The **template VM** in this guide refers to a regular vSphere VM and not VM
Templates according to the vSphere terminology. The difference is quite subtle,
Expand Down