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 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.

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.

  1. Alauda Container Platform Cluster Bootstrap Provider
  2. 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:

ac config use-cluster global
ac get minfo -l cpaas.io/module-name=cluster-api-provider-vsphere
ac get minfo -l cpaas.io/module-name=cluster-api-provider-kubeadm
ac get crd | grep -E '^vsphere[a-z]+\.infrastructure\.cluster\.x-k8s\.io\b'
ac get validatingwebhookconfiguration \
  -o jsonpath='{range .items[*]}{range .webhooks[*]}{.name}{"\n"}{end}{end}' \
  | grep -E 'vsphere|capv'

Continue when:

  • Both plugins are listed and Running.
  • The CRD list holds nine CRDs: vsphereclusters, vsphereclusteridentities, vsphereclustertemplates, vspheredeploymentzones, vspherefailuredomains, vspheremachines, vspheremachineconfigpools, vspheremachinetemplates, and vspherevms, each in infrastructure.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, and validation.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.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 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/etcd as 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 guestinfo user 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:

ac config use-cluster global
ac -n cpaas-system 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.

Next Steps

After the provider is installed, continue with: