Back to articles
6 min read

Step-by-Step Guide: Deploy and verify VKS Cluster using kubectl

In this article, we explore how to deploy a VKS cluster on vSphere using kubectl. The guide explains the cluster yaml configuration, deployment steps, and verification process in a simple and beginner-friendly way.

HC
December 3, 2025Updated Jun 25, 20261,128 words
Step-by-Step Guide:  Deploy and verify VKS Cluster using kubectl

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.

text
[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.

text
[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:

  1. Kubernetes version
  2. Control plane configuration
  3. Worker nodepools configuration
  4. Storage Class and VM Class

Replace the values in the following YAML according to your infrastructure and save the file as vks-cluster.yaml.

text
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.

ParameterDescription
apiVersionDefines the API version used for the Cluster resource. In this example, the cluster is created using the Cluster API (cluster.x-k8s.io).
kindSpecifies the Kubernetes resource type being created. Here it is a Cluster resource.
metadata.nameThe name of the VKS cluster that will be created. This name uniquely identifies the cluster.
metadata.namespaceThe Supervisor namespace where the VKS cluster will be deployed.
spec.clusterNetwork.pods.cidrBlocksDefines the IP address range used by Kubernetes Pods inside the cluster.
spec.clusterNetwork.services.cidrBlocksDefines the IP address range used for Kubernetes Services.
spec.clusterNetwork.serviceDomainDefines the internal DNS domain used within the cluster (commonly cluster.local).
topology.classRef.nameSpecifies the ClusterClass used for deployment. This defines the base configuration template for VKS clusters.
topology.classRef.namespaceNamespace where the ClusterClass is located. In VKS deployments, this is typically vmware-system-vks-public.
topology.versionThe Kubernetes version used for the cluster. Available versions can be checked using kubectl get kr.
topology.controlPlane.replicasNumber of control plane nodes. Supported values are typically 1 for development and 3 for production environments.
variables.vmClassDefines the VM size used for cluster nodes. This determines CPU and memory allocation.
variables.storageClassSpecifies the storage policy used for Kubernetes volumes and node disks.
variables.kubernetes.etcdConfiguration.maximumDBSizeGiBSets the maximum size allowed for the etcd database.
workers.machineDeployments.nameName of the worker node pool.
workers.machineDeployments.replicasNumber of worker nodes created in the cluster.
workers.machineDeployments.classSpecifies the worker node pool type defined in the ClusterClass.
workers.machineDeployments.variables.overrides.vmClassOverrides the VM class used specifically for worker nodes.
workers.machineDeployments.variables.overrides.volumesDefines 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.

text
# 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.

text
[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>

text
[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.2

In 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.

Attachments (1)

Practice Lab

How did you find this article?

Share:
399 views 0 claps 0 comments

Responses (0)

Sign in to join the conversation.

No responses yet. Be the first to share your thoughts!