Create a Cluster on VMware vSphere
ACP CLI (ac) renders the Cluster API, vSphere, and CPI objects from one install-config.yaml, applies them to the global cluster, and reports the creation stages. Every object lives in the cpaas-system namespace of the global cluster. For how the provider objects fit together, see How It Works.
TOC
PrerequisitesProcedure1. Writeinstall-config.yaml2. Create the Cluster3. Monitor the Creation4. Verify the ClusterCPI and PoolsPersistent DisksOptional TopologySelf-built VIPRun create AgainNext StepsPrerequisites
- You meet the VMware vSphere prerequisites.
acis logged in to the platform as a platform administrator (ac login https://<platform-address> --name <session-name>).
Procedure
1. Write install-config.yaml
Create an installation directory for the cluster and write install-config.yaml in it. ac writes manifests/ and logs/ac.log in the same directory.
Copy the following template and fill in the placeholders. The table below the template describes the numbered lines, which are specific to VMware vSphere. For the other fields, see Common install-config.yaml Fields. For the objects that ac renders from this file, see Parameters.
2. Create the Cluster
Run the following command from a machine where ac is logged in to the platform:
Before ac changes anything, it checks the following:
- The provider CRDs on the
globalcluster. - The credential and the vCenter sign-in.
- The vCenter objects named in
install-config.yaml. - The registry.
If a check fails, nothing is changed, and the error names the failed item.
create returns as soon as the objects are applied. The cluster keeps building after that. To wait until all stages are ready, add --wait. --timeout (default 2h) limits only the wait. To render the objects without applying them, run ac adm alpha cluster manifests with the same flags.
3. Monitor the Creation
Continue when all four stages are ready; otherwise see Troubleshooting.
4. Verify the Cluster
Run the following commands from a machine where ac is logged in to the platform:
Continue when every node is Ready; otherwise see Troubleshooting.
CPI and Pools
Continue when a ClusterResourceSetBinding exists for the cluster, vsphere-cloud-controller-manager is listed in kube-system, and each pool of the cluster shows READY True with ALLOCATED equal to the number of its machines; otherwise see Troubleshooting.
Persistent Disks
Run the following commands once for each pool, <cluster-name>-control-plane and <cluster-name>-<group>:
Continue when every persistent disk of an allocated slot reports Attached; otherwise see Troubleshooting.
Optional Topology
Applies to: node groups with network.additions or rawDisks. Skip it when you use neither.
On a node of that group:
Continue when each slot lists the declared additional NICs and disks, and every raw disk appears in /dev/disk/by-capv/; otherwise contact technical support.
Self-built VIP
Applies to: type: internal. Skip it for an external load balancer.
Continue when the condition is True and one Alive Pod runs on each control plane node; otherwise see Troubleshooting.
Log in to a control plane node of the cluster as the boot user (ssh boot@<control-plane-node-ip>). Use the private key that matches one of the SSH public keys in cluster.sshKeys. Run curl with sudo, because only root can read the cluster CA file:
Continue when it prints ok; otherwise see Troubleshooting.
Run create Again
create only creates a cluster. Do not run it on a cluster that already exists. To change a running cluster, see Manage Nodes.
If create stops before the cluster is created, run the same command again. It skips the work that is already done.
When you run create again on the same directory:
- It recreates objects that were deleted, except the credential Secret, which
acdoes not render. - It does not overwrite a field that was changed with another tool. When the rendered value differs,
createstops and reports that another manager owns the fields. Do not delete the object that the error names. - When
manifests/already exists,createasks whether to reuse it. Press Enter to reuse it, or answernto render again after you changeinstall-config.yaml. When standard input is not a terminal, pass--reuse-manifests=trueor--reuse-manifests=false. - Reusing
manifests/ignoresinstall-config.yamland skips every check.
Do not edit the files in manifests/.
Keep <install-dir>/manifests/, or set cluster.encryptionProviderConfig. A generated encryption key is kept only in manifests/. If you render again without doing either, a new key is generated, and manifests/ no longer records the key that the cluster uses.