Deploy and Verify VKS Cluster using kubectl
This tutorial focuses on clarity and simplicity, so even if you are new to VKS or Kubernetes, you should be able to follow along.
In case if you are not aware what VKS Cluster please visit the article VKS Cluster Overview
Prerequisites
First, make sure supervisor namespace has been created and attached with required storage policies, VM Class template and User permission.
Below we’re using the latest release available at the time, VKr 1.35.0 and VKS 3.6.0
Deploying a VKS cluster using kubectl typically involves the following steps:
- Login to the Supervisor Cluster
- Prepare the VKS Cluster Configuration YAML
- Deploy the VKS Cluster
- Monitor Cluster Creation
- Access the VKS Cluster
Step 1 — Login to the Supervisor Cluster
Before creating a VKS cluster, you must connect to the vSphere Supervisor Cluster. This is done using the kubectl vsphere login command.
[root@vks]# export KUBECTL_VSPHERE_PASSWORD='VKSRocks!23' [root@vks]# kubectl vsphere login --server=192.168.100.100 -u Administrator@vks.local --insecure-skip-tls-verify Logged in successfully.
Ex: kubectl vsphere login --server=<supervisor_ip> -u <vc_sso_user/devops_user> --insecure-skip-tls-verify
Note: Use --insecure-skip-tls-verify only for lab environments. For production environments, it is recommended to use proper CA certificates.
To verify connectivity:
If the command returns Supervisor nodes, the login is successful.
[root@vks]# kubectl get nodes NAME STATUS ROLES AGE VERSION 4201216380cc10d8dd06506866f23335 Ready control-plane,master 7h45m v1.31.6+vmware.3-fips 4201471245b7e1a8d8c6f8f4709830af Ready control-plane,master 7h44m v1.31.6+vmware.3-fips 420181be87b05521f1d6762a787ce761 Ready control-plane,master 7h45m v1.31.6+vmware.3-fips vks-demo-01 Ready agent 6h36m v1.31.6-sph-vmware-clustered-infravisor-trunk-85-g71ed1bf vks-demo-02 Ready agent 6h50m v1.31.6-sph-vmware-clustered-infravisor-trunk-85-g71ed1bf vks-demo-03 Ready agent 6h20m v1.31.6-sph-vmware-clustered-infravisor-trunk-85-g71ed1bf
Step 2 —Prepare the VKS Cluster Configuration YAML
The YAML file typically contains:
- Kubernetes version
- Control plane configuration
- Worker nodepools configuration
- Storage Class and VM Class
Replace the values in the following YAML according to your infrastructure and save the file as vks-cluster.yaml.
apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
metadata:
name: <vks_cluster_name>
namespace: <supervisor_namespace_name>
spec:
clusterNetwork:
pods:
cidrBlocks:
- 192.0.2.0/16
serviceDomain: cluster.local
services:
cidrBlocks:
- 198.51.100.0/12
topology:
classRef:
name: <cluster_class_name> # (kubectl get cc -n vmware-system-vks-public)
namespace: vmware-system-vks-public
controlPlane:
metadata:
annotations:
run.tanzu.vmware.com/resolve-os-image: os-name=photon
replicas: 3 # supported values 1 or 3
variables:
- name: vmClass
value: <vm_class_name>
- name: storageClass
value: <storage_class_name> # (kubectl get sc)
- name: kubernetes
value:
etcdConfiguration:
maximumDBSizeGiB: 4
version: <kubernetes_version> # (kubectl get kr)
workers:
machineDeployments:
- class: node-pool
metadata:
annotations:
run.tanzu.vmware.com/resolve-os-image: os-name=photon
name: photon-worker-node
replicas: 3
variables:
overrides:
- name: vmClass
value: <vm_class_name>
- name: volumes
value:
- name: kubelet-dir
mountPath: /var/lib/kubelet
capacity: 5Gi
storageClass: <storage_class_name>
- name: containerd-dir
mountPath: /var/lib/containerd
capacity: 20Gi
storageClass: <storage_class_name>Explanation of Important YAML Parameters
The following table explains the key parameters used in the VKS cluster configuration YAML.
| Parameter | Description |
|---|---|
| apiVersion | Defines the API version used for the Cluster resource. In this example, the cluster is created using the Cluster API (cluster.x-k8s.io). |
| kind | Specifies the Kubernetes resource type being created. Here it is a Cluster resource. |
| metadata.name | The name of the VKS cluster that will be created. This name uniquely identifies the cluster. |
| metadata.namespace | The Supervisor namespace where the VKS cluster will be deployed. |
| spec.clusterNetwork.pods.cidrBlocks | Defines the IP address range used by Kubernetes Pods inside the cluster. |
| spec.clusterNetwork.services.cidrBlocks | Defines the IP address range used for Kubernetes Services. |
| spec.clusterNetwork.serviceDomain | Defines the internal DNS domain used within the cluster (commonly cluster.local). |
| topology.classRef.name | Specifies the ClusterClass used for deployment. This defines the base configuration template for VKS clusters. |
| topology.classRef.namespace | Namespace where the ClusterClass is located. In VKS deployments, this is typically vmware-system-vks-public. |
| topology.version | The Kubernetes version used for the cluster. Available versions can be checked using kubectl get kr. |
| topology.controlPlane.replicas | Number of control plane nodes. Supported values are typically 1 for development and 3 for production environments. |
| variables.vmClass | Defines the VM size used for cluster nodes. This determines CPU and memory allocation. |
| variables.storageClass | Specifies the storage policy used for Kubernetes volumes and node disks. |
| variables.kubernetes.etcdConfiguration.maximumDBSizeGiB | Sets the maximum size allowed for the etcd database. |
| workers.machineDeployments.name | Name of the worker node pool. |
| workers.machineDeployments.replicas | Number of worker nodes created in the cluster. |
| workers.machineDeployments.class | Specifies the worker node pool type defined in the ClusterClass. |
| workers.machineDeployments.variables.overrides.vmClass | Overrides the VM class used specifically for worker nodes. |
| workers.machineDeployments.variables.overrides.volumes | Defines additional volumes mounted on worker nodes (for example kubelet or container runtime storage). |
Step 3 — Deploy the VKS Cluster
Once the YAML file is ready, you can deploy the cluster using kubectl. Following Kubernetes command will send request to the Supervisor Cluster which then starts creating the VKS cluster resources.
# Run on Supervisor context [root@vks]# kubectl apply -f vks-cluster.yaml cluster.cluster.x-k8s.io/vks-cluster created
Step 4 — Monitor VKS Cluster Creation
Cluster deployment usually takes a few minutes. When the AVAILABLE become True and Desired Control Plane and Worker Node replicas are running fine, the cluster is fully deployed.
[root@vks]# kubectl get cluster -A NAMESPACE NAME CLUSTERCLASS AVAILABLE CP DESIRED CP AVAILABLE CP UP-TO-DATE W DESIRED W AVAILABLE W UP-TO-DATE PHASE AGE VERSION vks-cluster-namespace vks-cluster builtin-generic-v3.6.0 True 3 3 3 3 3 3 Provisioned 92m v1.35.0+vmware.2
Step 5 — Access the VKS Cluster
Once the VKS cluster is ready, you can retrieve the kubeconfig and access the cluster.
To retrieve the kubeconfig you can run the following command on supervisor cluster.
Ex: kubectl get secret <vks_cluster_name>-kubeconfig -n <supervisor_namespace_name> -o jsonpath='{.data.value}' | base64 -d > <kubeconfig_file_name>
[root@vks]# kubectl get secret vks-cluster-kubeconfig -n vks-cluster-namespace -o jsonpath='{.data.value}' | base64 -d > vks-cluster-kubeconfig
[root@vks]# export KUBECONFIG=vks-cluster-kubeconfig
[root@vks]# kubectl get nodes -A
NAME STATUS ROLES AGE VERSION
vks-cluster-hsd6b-cz92l Ready control-plane 88m v1.35.0+vmware.2
vks-cluster-hsd6b-jpjxh Ready control-plane 89m v1.35.0+vmware.2
vks-cluster-hsd6b-tst6c Ready control-plane 91m v1.35.0+vmware.2
vks-cluster-photon-worker-node-xhph8-cmf9l-2hk9n Ready <none> 90m v1.35.0+vmware.2
vks-cluster-photon-worker-node-xhph8-cmf9l-gvcsl Ready <none> 90m v1.35.0+vmware.2
vks-cluster-photon-worker-node-xhph8-cmf9l-t667r Ready <none> 90m v1.35.0+vmware.2In this article, we learned how to deploy a VKS cluster using a simple YAML configuration and kubectl.
Once the VKS Cluster is ready, the next step is to deploy platform services and application workloads. One common requirement in modern Kubernetes environments is service mesh, which provides traffic management, observability, and security for microservices, please refer the article here
Disclaimer
This blog is for informational and educational purposes only. The configurations, examples, and architectural guidance provided are based on general best practices and publicly available references.
Always validate configurations in a non-production environment before applying them to live systems. Features and integrations may vary depending on the versions of VKS, VKr, LCI, Supervisor and vCenter Server being used. The author is not responsible for any unintended impact caused by the use of this information in production environments.
Contents, and opinions are my own and do not reflect the opinions of my employer.
