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 before you create the first workload cluster on VMware vSphere when the global cluster runs on other infrastructure: ac installs only that infrastructure's provider. A global cluster installed on VMware vSphere with ACP CLI (ac) already runs both providers, and you can skip this page. 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.
Prerequisites
Before installing the provider, ensure the following conditions are met:
- You can access the
globalcluster. - You can access Customer Portal to download provider packages.
- The vCenter account that clusters will reference through
VSphereCluster.spec.identityRefcan list, create, and set VM custom attributes. Grant the Global → Manage custom attributes and Global → Set custom attribute privileges. The provider requires them whenever aVSphereClusteror its CAPIClustercarries anyvsphere.cluster.x-k8s.io/*annotation, and a missing privilege fails VM reconciliation rather than skipping the metadata write.
Steps
Download the required packages
To create clusters on VMware vSphere, you need two cluster plugins. Download both from the Customer Portal. For 4.5, they are in ACP Common Aligned Extensions; see Download.
- Alauda Container Platform Cluster Bootstrap Provider
- Alauda Container Platform Infrastructure Provider for Virtualization Platform
Upload the packages
Upload both packages to the platform with violet push. For the command and its parameters, refer to Upload Packages.
Install the cluster plugins
Install both cluster plugins on the global cluster. For the procedure, refer to Cluster Plugin.
Verify the installation
Run the following commands from a machine where ac is logged in to the platform:
Continue when:
- Both plugins are listed and
Running. - The CRD list holds nine CRDs:
vsphereclusters,vsphereclusteridentities,vsphereclustertemplates,vspheredeploymentzones,vspherefailuredomains,vspheremachines,vspheremachineconfigpools,vspheremachinetemplates, andvspherevms, each ininfrastructure.cluster.x-k8s.io. - The webhook list includes
validation.vspherecluster.infrastructure.cluster.x-k8s.io,validation.vspheremachineconfigpool.infrastructure.cluster.x-k8s.io,validation.vspheremachinetemplate.infrastructure.cluster.x-k8s.io, andvalidation.kubeadmcontrolplane.capv.cluster.x-k8s.io.
Otherwise, install the missing plugin again as in Cluster Plugin, or contact technical support.
Upgrading the Provider
The provider is an Aligned Extension and is upgraded together with the global cluster. Publish the target-version provider package with violet as described in Prepare for the Upgrade; the Cluster Version Operator (CVO) then upgrades the installed cluster plugin as part of the cluster upgrade. See Upgrade 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.controlPlaneLoadBalancerunset, 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[].volumePathand.diskUUID, and per-slot reclaim state understatus.configStatuses[].reclaimStatus, are folded intostatus.persistentDiskStatuses[]. A reclaim that was in flight keeps its phase and task reference and continues, andreclaimStatusis then cleared so status has a single source of truth. - The deprecated
specfields are left in the object. Treat them as history and readstatus.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 —
maxSurgeandreplicas— are never rewritten, so an existingKubeadmControlPlaneorMachineDeploymentthat does not carry them still has to be corrected by hand. See Set the Rollout Settings.
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; see Control Plane Endpoint.
- A pool keeps the disk lists it was created with. The upgrade moves no existing disk into
spec.configs[].ephemeralDisks[]: a cluster created on an earlier ACP version keeps/var/cpaas,/var/lib/containerd, and/var/lib/etcdas persistent disks. The persistent-plus-ephemeral split documented for new clusters is a creation-time layout. See Add Data Disks. - Guest-side changes delivered through
guestinfouser data, such as the pod-log relocation, reach a node only when it is replaced. See Pod Log Directory.
Confirm the result with the checks in Verify the installation, then read one pool back:
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.
Next Steps
After the provider is installed, continue with: