Prerequisites for VMware vSphere Workload Clusters

Meet the following before you create the cluster. ac does not create any of the vCenter objects that this page lists. It checks them before it applies anything.

Providers

Make sure that the Cluster Bootstrap Provider and the Infrastructure Provider for Virtualization Platform are installed on the global cluster. A global cluster that was installed on VMware vSphere with ac already runs both. Otherwise, see Install the Provider.

vCenter Reachability

Allow the flows to vCenter that VMware vSphere lists. The sources are the global cluster, the workload cluster nodes, and the machine that runs ac.

VM Template

Make sure that the VM template, the datacenter, the port groups, the datastores, and the compute resource exist in vCenter. Create the VM template from the Alauda OS image published for the target platform release, and do not modify the image. The image carries the Kubernetes version that ac installs, which is the latest Kubernetes version that the platform supports. See OS Support Matrix.

VM Template ConfigMap

Register each VM template with a ConfigMap on the global cluster when you create the template. Creating a cluster does not read these ConfigMaps; the platform upgrade does. ACP cannot discover the VM templates in your vCenter, so the upgrade learns them only from these ConfigMaps. Create one ConfigMap per VM template. The ConfigMap records:

  • The name of the VM template.
  • The ACP version whose Alauda OS image the VM template was made from.
  • The Kubernetes version and etcd tag of that ACP version.

The platform upgrade uses these ConfigMaps to find the VM template of each Kubernetes version, so every vSphere cluster needs them. Before an upgrade, deploy the VM template of every version on the upgrade path, with the same name, in every datacenter that the cluster uses. Then register each VM template, as described in Stage the Alauda OS Images.

Follow these rules:

  • Keep the ConfigMaps of earlier ACP versions.
  • For each ACP version, register only one VM template.
  • The value of the cpaas.io/vsphere-vm-template label must match the VM template name in vCenter.

Run ac config use-cluster global first, and then run the command that the generator prints.

v4.5.0 · Kubernetes v1.36.4-acp.3
ac apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: vsphere-vm-template-m55-v4.5.0
  namespace: cpaas-system
  labels:
    cpaas.io/vsphere-vm-template: "<vm-template-name>"
    cpaas.io/distribution-version: "v4.5.0"
data:
  kubernetesVersion: "v1.36.4-acp.3"
  etcdTag: "v3.6.13-acp.5"
EOF

Run the command on the global cluster. In a DR environment, run it on both global clusters: the ConfigMaps are not synchronized between them.

For each ACP version, register VM templates of only one OS on a global cluster. When VM templates of different OSes have the same Kubernetes version, an upgrade can move a cluster to the other OS.

Check that the ConfigMap of your VM template exists. Run the following commands from a machine where ac is logged in to the platform:

ac config use-cluster global
ac -n cpaas-system get cm -l cpaas.io/vsphere-vm-template -L cpaas.io/vsphere-vm-template

If no ConfigMap lists your VM template name, create the ConfigMap of your VM template.

Control Plane Endpoint

Every cluster reaches its API server through a stable endpoint. Choose the mode before you write install-config.yaml. You cannot change the mode after the cluster is created. For example, an existing cluster cannot switch to a Self-built VIP.

Endpoint modeWho provides the endpoint
External load balancer (default)You provide it. Provision an external Layer 4 TCP load balancer that satisfies the External Load Balancer requirements.
Self-built VIPThe provider runs a Self-built VIP on the control plane nodes. Meet the Self-built VIP requirements first.

Static IP Addresses

Give every node a hostname and a static IPv4 address, plus one address for each additional NIC. Make sure that every address is allocated and not in use. Plan the addresses and disks of each host before you create the cluster. After a machine takes a slot, you cannot change them; see Allocated slot restrictions.

ClusterResourceSet

The vSphere cloud provider reaches the workload cluster through a Cluster API ClusterResourceSet on the global cluster. You do not prepare anything for it. If the nodes stay uninitialized after the cluster is created, see Troubleshooting.

Image Registry

The cluster pulls its platform components either from the registry of the global cluster or from a dedicated registry. See Choose the Image Registry for a Workload Cluster. The registry must be reachable from the workload nodes. It must contain what the cluster needs: the Kube-OVN chart and CoreDNS repositories and the vSphere CPI tag.

vCenter Credential Secret

Create the vCenter credential Secret in the cpaas-system namespace of the global cluster. ac never creates it. The cluster references the Secret by name. Unlike the global cluster, it does not hold an inline credential. Use an editor to write the account to vsphere-credential.env, with one key=value per line and no quotes:

vsphere-credential.env
username=<administrator@vsphere.local>
password=<password>

Keep the file private (chmod 600 vsphere-credential.env), because it holds the password.

Run the following commands from a machine where ac is logged in to the platform. The last command removes the file:

ac config use-cluster global
ac -n cpaas-system create secret generic <cluster-name>-credential --from-env-file=vsphere-credential.env
rm -f vsphere-credential.env

Do not create the Secret with ac apply, because it stores the password in an annotation of the Secret.

Use one Secret per cluster. The provider deletes the Secret when it deletes the cluster. Create the Secret again before you recreate a cluster. ac renders the CPI credential from the same account. You do not prepare a second one.

The account must be able to read the inventory. It must also be able to clone, power, reconfigure, and delete VMs and their disks. When custom attributes are in use, the account needs the privileges listed in Install the Provider.

Node Labels and Taints

To dedicate node groups to a purpose such as monitoring, logging, or ingress, plan their role labels and taints before you create the cluster, as described in Infra Nodes.