Workflow for Provisioning Tanzu Kubernetes Clusters Using the Tanzu Kubernetes Grid Service v1alpha1 API

You provision Tanzu Kubernetes clusters by invoking the Tanzu Kubernetes Grid Service declarative API using kubectl and a cluster specification defined using YAML. After you provision a cluster, you operate it and deploy workloads to it using kubectl.

The workflow provides an end-to-end procedure for the cluster provisioning process. Each of the steps has links for more information about the specific task.

Prerequisites

Note: The TKG v1alpha1 API is deprecated and should not be used to create new TKG clusters. Use the TKG v1alpha2 API instead. See Provisioning Tanzu Kubernetes Clusters Using the TKGS v1alpha2 API.

Complete the following prerequisites:

Configure a Supervisor Cluster instance. See Configuring and Managing a Supervisor Cluster.
Create a vSphere Namespace where you plan to provision Tanzu Kubernetes clusters. See Create and Configure a vSphere Namespace.
The initial namespace configuration requires the following:
- Edit permissions for one or more DevOps engineers to access the namespace using vCenter Single Sign-On credentials.
- Tag-based shared storage policy for the namespace.
- Capacity and usage quotas for the namespace, verified and adjusted, as necessary.
Create a content library for Tanzu Kubernetes releases on a shared datastore and synchronize the releases you want to use. See Creating and Managing Content Libraries for Tanzu Kubernetes releases.
Associate the content library and the virtual machine classes with the vSphere Namespace. See Configure a vSphere Namespace for Tanzu Kubernetes releases.

Procedure

Download and install the Kubernetes CLI Tools for vSphere. See Download and Install the Kubernetes CLI Tools for vSphere.
Using the vSphere Plugin for kubectl, authenticate with the Supervisor Cluster. See Connect to the Supervisor Cluster as a vCenter Single Sign-On User.
```
kubectl vsphere login --server=IP-ADDRESS --vsphere-username USERNAME
```
Using kubectl, switch context to the vSphere Namespace where you plan to provision the Tanzu Kubernetes cluster.
```
kubectl config get-contexts
```
```
kubectl config use-context SUPERVISOR-NAMESPACE
```
For example:
```
kubectl config use-context tkgs-cluster-ns
```
List the available virtual machine class bindings. See Virtual Machine Classes for Tanzu Kubernetes Clusters.
Use the following command to list all VM class bindings that are available in the vSphere Namespace where you deploy the cluster.
```
kubectl get virtualmachineclassbindings
```
Note: The command kubectl get virtualmachineclasses lists all the VM classes present on the Supervisor Cluster. Because you must associate VM classes with the vSphere Namespace, you can only use those VM classes that are bound to the target namespace.
Get the available default storage class by describing the namespace.
```
kubectl describe namespace SUPERVISOR-NAMESPACE
```
List the available Tanzu Kubernetes releases.
Note: Refer to the list of Tanzu Kubernetes releases for compatibility. See Verify Tanzu Kubernetes Cluster Compatibility for Update.
```
kubectl get tanzukubernetesreleases
```
Note: The command kubectl get virtualmachineimages returns generic information about the virtual machines.

Construct the YAML file for provisioning a Tanzu Kubernetes cluster.

Start with one of the example YAML files. See Examples for Provisioning Tanzu Kubernetes Clusters Using the Tanzu Kubernetes Grid Service v1alpha1 API.

For example, the following YAML file provisions a minimal cluster using all available defaults:

apiVersion: run.tanzu.vmware.com/v1alpha1  #TKGS API endpoint
kind: TanzuKubernetesCluster               #required parameter
metadata:
  name: tkgs-cluster-1                     #cluster name, user defined
  namespace: tgks-cluster-ns               #vsphere namespace
spec:
  distribution:
    version: v1.19                         #Resolves to latest TKR 1.19 version
  topology:
    controlPlane:
      count: 1                             #number of control plane nodes
      class: best-effort-medium            #vmclass for control plane nodes
      storageClass: vwt-storage-policy     #storageclass for control plane
    workers:
      count: 3                             #number of worker nodes
      class: best-effort-medium            #vmclass for worker nodes
      storageClass: vwt-storage-policy     #storageclass for worker nodes

Use the information you gleaned from the output of the preceding commands to populate the cluster YAML, including the namespace, storage class, and virtual machine class.
Customize the cluster as needed by referring to the full list of cluster configuration parameters. See Configuration Parameters for Tanzu Kubernetes Clusters Using the Tanzu Kubernetes Grid Service v1alpha1 API.
Save the file as tkgs-cluster-1.yaml, or similar.

Provision the cluster by running the following kubectl command.

kubectl apply -f CLUSTER-NAME.yaml

For example:

kubectl apply -f tkgs-cluster-1.yaml

Expected result:

tanzukubernetescluster.run.tanzu.vmware.com/tkgs-cluster-1 created

Monitor the deployment of cluster nodes using kubectl. See Monitor Tanzu Kubernetes Cluster Status Using kubectl.

kubectl get tanzukubernetesclusters

Sample result:

NAME             CONTROL PLANE   WORKER   DISTRIBUTION                     AGE     PHASE
tkgs-cluster-2   1               3        v1.19.7+vmware.1-tkg.1.c40d30d   7m59s   running

Monitor the deployment of cluster nodes using the vSphere Client. See Monitor Tanzu Kubernetes Cluster Status Using the vSphere Client.
For example, in the vSphere inventory you should see the virtual machine nodes being deployed in the namespace.
Run additional commands to verify cluster provisioning. See Use Tanzu Kubernetes Cluster Operational Commands.
For example:
```
kubectl get tanzukubernetescluster,cluster-api,virtualmachinesetresourcepolicy,virtualmachineservice,virtualmachine
```
Note: For additional troubleshooting, see Troubleshooting Tanzu Kubernetes Clusters.

Using the vSphere Plugin for kubectl, log in to the cluster. See Connect to a Tanzu Kubernetes Cluster as a vCenter Single Sign-On User.

kubectl vsphere login --server=IP-ADDRESS --vsphere-username USERNAME \
--tanzu-kubernetes-cluster-name CLUSTER-NAME --tanzu-kubernetes-cluster-namespace NAMESPACE-NAME

Verify cluster provisioning using the following kubectl commands.

kubectl cluster-info

kubectl get nodes

kubectl get namespaces

kubectl api-resources

Deploy an example workload and verify cluster creation. See Deploy Workloads on Tanzu Kubernetes Clusters.

Note: Tanzu Kubernetes clusters have pod security policy enabled. Depending on the workload and user, you might need to create an appropriate RoleBinding or custom PodSecurityPolicy. See Using Pod Security Policies with Tanzu Kubernetes Clusters.
Operationalize the cluster by deploying TKG Extensions. See Install Packages on Tanzu Kubernetes Clusters.