vSphere CSI Driver

Purpose: For platform engineers, shows how to configure vSphere CSI StorageClass, volume provisioning, and topology-aware scheduling.

What vSphere CSI Does

The vSphere CSI driver provisions Kubernetes persistent volumes backed by VMware vSphere VMDK datastores. It creates and manages virtual disks on vSphere datastores, attaching them to VMs running Kubernetes worker nodes. This driver is deployed on VMware provider clusters as the primary storage backend.

How It's Deployed

The vSphere CSI driver is deployed via FluxCD from openCenter-gitops-base:

openCenter-gitops-base/applications/base/services/vsphere-csi/
├── namespace.yaml
├── source.yaml
├── helmrelease.yaml
└── helm-values/
    └── hardened-values.yaml

Customer overlay:

applications/overlays/<cluster>/services/vsphere-csi/
├── kustomization.yaml
└── override-values.yaml

The driver requires vSphere credentials and vCenter connection details.

Key Configuration

vSphere Credentials

The driver authenticates to vCenter using credentials stored in a Kubernetes Secret. The secret is created by openCenter-cli and encrypted with SOPS:

# applications/overlays/<cluster>/services/vsphere-csi/override-values.yaml
vCenter:
  host: vcenter.example.com
  port: 443
  insecureFlag: false
  datacenters: DC01

The credential secret (username/password) is managed separately via SOPS-encrypted manifests in the overlay.

StorageClass Configuration

Define StorageClasses that map to vSphere datastore policies:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: vsphere-default
provisioner: csi.vsphere.vmware.com
allowVolumeExpansion: true
reclaimPolicy: Delete
parameters:
  storagepolicyname: "vSAN Default Storage Policy"
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: vsphere-retain
provisioner: csi.vsphere.vmware.com
allowVolumeExpansion: true
reclaimPolicy: Retain
parameters:
  storagepolicyname: "vSAN Default Storage Policy"

The storagepolicyname must match a storage policy defined in vCenter.

Topology-Aware Provisioning

For clusters spanning multiple vSphere zones or datastores, enable topology awareness:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: vsphere-zonal
provisioner: csi.vsphere.vmware.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  storagepolicyname: "vSAN Default Storage Policy"

WaitForFirstConsumer delays volume creation until a pod is scheduled, ensuring the volume is provisioned in the same zone as the pod.

Verification

# Check CSI driver pods
kubectl get pods -n vmware-system-csi

# Verify StorageClasses
kubectl get storageclass | grep vsphere

# Test volume provisioning
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: vsphere-default
  resources:
    requests:
      storage: 1Gi
EOF

# Check PVC is bound
kubectl get pvc test-pvc

# Clean up test
kubectl delete pvc test-pvc

Troubleshooting

PVC stuck in Pending: Verify vCenter credentials are correct and the Cinder/vSphere API is reachable. Check CSI controller logs:

kubectl logs -n vmware-system-csi -l app=vsphere-csi-controller -c vsphere-csi-controller

Volume attach failures: Ensure the VM hardware version supports the CSI driver (hardware version 15+ recommended). Check that the datastore has sufficient free space.

Common Customizations

• Multiple StorageClasses: Create classes for different storage policies (SSD vs. HDD, different RAID levels).
• Volume expansion: Enabled by default with allowVolumeExpansion: true. Expand PVCs by editing the spec.resources.requests.storage field.
• Snapshot support: Requires the external-snapshotter controller (deployed separately). Create VolumeSnapshotClass resources referencing the vSphere CSI driver.
• Resource limits: Adjust CSI controller resources in override-values.yaml for clusters with high volume churn.