#Install the VMware vSphere Provider

This document explains how to install the Infrastructure Provider for Virtualization Platform and the Cluster Bootstrap Provider, and how to verify that the required Cluster API components are available on the global cluster.

#When You Need This

Complete this page after the global cluster is installed and before you create the first workload cluster on VMware vSphere. It is required regardless of the IaaS platform that the global cluster itself runs on. In a disaster recovery (DR) pair, complete it on both global clusters, so that the standby can reconcile the same workload clusters after a failover. Upload the packages to each global cluster.

This is a separate task from the provider steps in Installing the global Cluster. Those steps upload provider packages to the temporary bootstrap cluster to create the global cluster itself.

#Prerequisites

Before installing the provider, ensure the following conditions are met:

• You can access the global cluster.
• You can access Customer Portal to download provider packages.
• The vCenter account that clusters will reference through VSphereCluster.spec.identityRef can list, create, and set VM custom attributes. Grant the Global → Manage custom attributes and Global → Set custom attribute privileges. The provider requires them whenever a VSphereCluster or its CAPI Cluster carries any vsphere.cluster.x-k8s.io/* annotation, and a missing privilege fails VM reconciliation rather than skipping the metadata write.
• To create or upgrade workload clusters, you work against the active management cluster, not a disaster-recovery standby. See Standby Management Clusters.

#Steps

kubectl get minfo -l cpaas.io/module-name=cluster-api-provider-vsphere
kubectl get minfo -l cpaas.io/module-name=cluster-api-provider-kubeadm

kubectl get crd | grep -E '^vsphere[a-z]+\.infrastructure\.cluster\.x-k8s\.io\b'

kubectl get validatingwebhookconfiguration \
  -o jsonpath='{range .items[*]}{range .webhooks[*]}{.name}{"\n"}{end}{end}' \
  | grep -E 'vsphere|capv'

#Upgrading the Provider

The provider is an Aligned extension and is upgraded together with the Distribution Version upgrade of the global cluster. Publish the target-version provider package with violet as described in Pre-Upgrade Preparation; CVO then upgrades the installed cluster plugin as part of the cluster upgrade. See Upgrade the Distribution Version of the global Cluster.

The upgrade also updates the provider CRDs. Some fields move between releases, but existing resources are migrated for you — do not hand-edit VSphereMachineConfigPool or any other provider object to match a new schema, and do not delete and recreate one. On its first reconcile after the upgrade the controller brings each object up to the current layout:

• The control plane endpoint is not touched. An existing cluster leaves spec.controlPlaneLoadBalancer unset, which is what an external LoadBalancer looks like, and it stays that way: the API server address does not change and nothing is deployed into the workload cluster.
• Per-disk state that used to be recorded on spec.configs[].persistentDisks[].volumePath and .diskUUID, and per-slot reclaim state under status.configStatuses[].reclaimStatus, are folded into status.persistentDiskStatuses[]. A reclaim that was in flight keeps its phase and task reference and continues, and reclaimStatus is then cleared so status has a single source of truth.
• The deprecated spec fields are left in the object. Treat them as history and read status.persistentDiskStatuses[] instead.
• The migration never overwrites a value that is already set, so it is safe to repeat. The disk part is status-only bookkeeping and runs before vCenter is contacted, so it completes even while vCenter is unreachable.
• It covers the provider's own resources only. The rollout values required on the Cluster API objects — maxSurge and replicas — are never rewritten, so an existing KubeadmControlPlane or MachineDeployment that does not carry them still has to be corrected by hand. See Check the manifests against the admission rules.

Nothing in the workload cluster is touched, and no VM is replaced. Three consequences are worth knowing before you upgrade:

• A cluster created on an earlier provider keeps its external LoadBalancer and cannot adopt the Self-built VIP. The endpoint is a deploy-time choice: it cannot be adjusted while the cluster runs, and an upgrade is not an opportunity to change it — filling in spec.controlPlaneLoadBalancer on a running cluster is rejected. See Control Plane Endpoint Modes.
• A pool keeps the disk lists it was created with. spec.configs[].ephemeralDisks[] is new in provider v1.0.17, but the upgrade moves no existing disk into it: a cluster created on an earlier provider keeps /var/cpaas, /var/lib/containerd, and /var/lib/etcd as persistent disks. The persistent-plus-ephemeral split documented for new clusters is a creation-time layout. See Standard data disks.
• Guest-side changes delivered through guestinfo user data, such as the pod-log relocation, reach a node only when it is replaced. See Relocating the pod log directory.

Confirm the result with the checks in Verify the installation, then read one pool back:

kubectl -n <namespace> get vspheremachineconfigpool <pool_name> \
  -o jsonpath='{range .status.persistentDiskStatuses[*]}{.hostname}{" "}{.name}{" "}{.phase}{"\n"}{end}'

Each disk that was already provisioned before the upgrade appears with a phase, and status.configStatuses[].reclaimStatus is gone. A disk on a slot that no Machine has ever allocated has no VMDK yet, so it has no record; that is expected rather than an incomplete migration.

#Standby Management Clusters

While the etcd-sync ConfigMap exists in the kube-public namespace, the provider treats the management cluster as a disaster-recovery standby:

• Objects owned by the reserved global cluster are still reconciled.
• Every other object is skipped and requeued every 30 seconds.
• An object whose cluster name cannot be determined is skipped as well.

Do not create or upgrade a workload cluster against a standby management cluster. The reconcilers no-op silently — no condition changes and no error appears on the resource, so the workflow looks stalled rather than blocked.

Check before you start:

kubectl -n kube-public get configmap etcd-sync -o name 2>/dev/null || echo "not standby"

A common mistake is to look in kube-system. The ConfigMap is in kube-public.

For the disaster-recovery workflow itself, see Global Cluster Disaster Recovery.

#Next Steps

After the provider is installed, continue with:

• VMware vSphere Infrastructure Preparation
• Create a Cluster on VMware vSphere
• Upgrade Kubernetes on VMware vSphere
• VMware vSphere Provider