Skip to main content

vSphere Prerequisites

Additional prerequisites for deploying CM Platform on VMware vSphere, where persistent volumes are backed by the vSphere Container Storage Plug-in (CSI).

1. Enable disk.EnableUUID on every node VM (day-0)​

The CSI driver matches virtual disks to devices inside the guest by their UUID. Without a stable UUID exposed to the guest, volume attach succeeds in vSphere but the pod never gets its device and stays in ContainerCreating.

Set the advanced VM parameter on every control-plane and worker VM, before installing k3s:

disk.EnableUUID = TRUE

vSphere Client → VM → Edit Settings → Advanced Parameters. The VM must be powered off; if the parameter is absent, add it. Retrofitting it later requires a power cycle of each node, so do it at VM-template time.

While preparing the templates, also make sure each VM has VMware Tools installed, hardware version 15 or later, and a VMware Paravirtual SCSI controller.

2. Run the cluster with an external cloud provider​

CSI requires the out-of-tree vSphere CPI to label nodes with their providerID. Whatever Kubernetes distribution you use, kubelet must run with cloud-provider=external on every node, and any in-tree or bundled cloud controller must be off — otherwise the two race to initialize nodes.

Nodes stay NotReady with an uninitialized taint until the CPI is deployed — that is expected. Install the CPI first, then the CSI driver.

k3s​

k3s bundles both a cloud controller and ServiceLB, so both need disabling. Extend the cluster creation inventory with:

    server_config_yaml: |
      disable:
        ...
        - servicelb          # vSphere: ServiceLB conflicts with the vSphere CPI
      disable-cloud-controller: true
      kubelet-arg:
        - "cloud-provider=external"

    agent_config_yaml: |
      kubelet-arg:
        - "cloud-provider=external"

OpenShift/OKD​

Clusters installed with the vSphere platform integration are already configured for the external provider — no change needed. See the OpenShift/OKD prerequisites for the remaining platform-specific steps.