Skip to content

vSphere Quick Start#

Much of the following includes the process of setting up credentials for vSphere. To better understand how Project 2A uses credentials, read the Credential System.

Prerequisites#

2A Management Cluster#

You need a Kubernetes cluster with 2A installed.

Software & VMware-specific prerequisites#

  1. kubectl CLI installed locally.
  2. vSphere instance version 6.7.0 or higher.
  3. vSphere account with appropriate privileges.
  4. Image template.
  5. vSphere network with DHCP enabled.

vSphere privileges#

To function properly, the user assigned to the vSphere Provider should be able to manipulate vSphere resources. The following is the general overview of the required privileges:

  • Virtual machine - full permissions are required
  • Network - Assign network is sufficient
  • Datastore - it should be possible for user to manipulate virtual machine files and metadata

In addition to that, specific CSI driver permissions are required. See the official doc for more information on CSI-specific permissions.

Image template#

You can use pre-built image templates from the CAPV project or build your own.

When building your own image, make sure that VMware tools and cloud-init are installed and properly configured.

You can follow the official open-vm-tools guide on how to correctly install VMware tools.

When setting up cloud-init, you can refer to the official docs and specifically the VMware datasource docs for extended information regarding cloud-init on vSphere.

vSphere network#

When creating a network, make sure that it has DHCP service.

Also, ensure that part of your network is out of the DHCP range (e.g., network 172.16.0.0/24 should have DHCP range 172.16.0.100-172.16.0.254 only). This is needed to ensure that LB services will not create any IP conflicts in the network.

Step 1: Create a Secret Object with the username and password#

The Secret stores the username and password for your vSphere instance.

Save the Secret YAML into a file named vsphere-cluster-identity-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: vsphere-cluster-identity-secret
  namespace: hmc-system
stringData:
  username: <user>
  password: <password>
type: Opaque

Apply the YAML to your cluster using the following command:

kubectl apply -f vsphere-cluster-identity-secret.yaml

Step 2: Create the VSphereClusterIdentity Object#

This object defines the credentials CAPV will use to manage vSphere resources.

Save the VSphereClusterIdentity YAML into a file named vsphere-cluster-identity.yaml:

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: VSphereClusterIdentity
metadata:
  name: vsphere-cluster-identity
spec:
  secretName: vsphere-cluster-identity-secret
  allowedNamespaces:
    selector:
      matchLabels: {}

Apply the YAML to your cluster:

kubectl apply -f vsphere-cluster-identity.yaml

Step 3: Create the 2A Credential Object#

Create a YAML with the specification of our credential and save it as vsphere-cluster-identity-cred.yaml

apiVersion: hmc.mirantis.com/v1alpha1
kind: Credential
metadata:
  name: vsphere-cluster-identity-cred
  namespace: hmc-system
spec:
  identityRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: VSphereClusterIdentity
    name: vsphere-cluster-identity

Warning

.spec.identityRef.kind must be VSphereClusterIdentity and the .spec.identityRef.name must match the .metadata.name of the VSphereClusterIdentity object above.

Apply the YAML to your cluster:

kubectl apply -f vsphere-cluster-identity-cred.yaml

Step 4: Create your first Managed Cluster#

Create a YAML with the specification of your Managed Cluster and save it as my-vsphere-managedcluster1.yaml.

Here is an example of a ManagedCluster YAML file:

apiVersion: hmc.mirantis.com/v1alpha1
kind: ManagedCluster
metadata:
  name: my-vsphere-managedcluster1
  namespace: hmc-system
spec:
  template: <template-name> # The name of the template you want to use from above
  credential: vsphere-cluster-identity-cred
  config:
    vsphere:
      server: <VSPHERE_SERVER>
      thumbprint: <VSPHERE_THUMBPRINT>
      datacenter: <VSPHERE_DATACENTER>
      datastore: <VSPHERE_DATASTORE>
      resourcePool: <VSPHERE_RESOURCEPOOL>
      folder: <VSPHERE_FOLDER>
    controlPlaneEndpointIP: <VSPHERE_CONTROL_PLANE_ENDPOINT>
    controlPlane:
      ssh:
        user: ubuntu
        publicKey: <VSPHERE_SSH_KEY>
      vmTemplate: <VSPHERE_VM_TEMPLATE>
      network: <VSPHERE_NETWORK>
    worker:
      ssh:
        user: ubuntu
        publicKey: <VSPHERE_SSH_KEY>
      vmTemplate: <VSPHERE_VM_TEMPLATE>
      network: <VSPHERE_NETWORK>

Note

For more information about the config options, see the vSphere Template Parameters.

Apply the YAML to your management cluster:

kubectl apply -f my-vsphere-managedcluster1.yaml

There will be a delay as the cluster finishes provisioning. Follow the provisioning process with the following command:

kubectl -n hmc-system get managedcluster.hmc.mirantis.com my-vsphere-managedcluster1 --watch

After the cluster is Ready, you can access it via the kubeconfig, like this:

kubectl -n hmc-system get secret my-vsphere-managedcluster1-kubeconfig -o jsonpath='{.data.value}' | base64 -d > my-vsphere-managedcluster1-kubeconfig.kubeconfig

KUBECONFIG="my-vsphere-managedcluster1-kubeconfig.kubeconfig" kubectl get pods -A