vSphere with Kubernetes: Introduction to vSphere Supervisor cluster REST APIs

vSphere 7.0 is now generally available and without a doubt “vSphere with Kubernetes” (former project pacific) is biggest highlights of the release. I think, this will have similar or even bigger impact on IT landscape since the launch of ESXi or vMotion in the past. Coolest thing is that VMs and containers can co-exist and no tools to manage them are changing. I am personally very happy that vSphere is now just not about VMs but also containers & beyond (read “vThinkBeyondVM”) as well.

Note: As you already might know “vSphere with Kubernetes” is available through VMware Cloud Foundation(VCF). I highly recommend you to read this quick post on how to get “vSphere with Kubernetes”? Post is written by none other than Kit Colbert . Very straight and simplified post if you ask me.

Before I discuss about REST APIs, I would like to provide brief about 2 important constructs below i.e. ” Supervisor cluster” and “Tanzu Kubernetes Cluster” (aka Guest cluster). Please refer vSphere with Kubernetes 101 white paper for more details.

Supervisor cluster : It is a special kind of Kubernetes cluster, where ESXi hosts inside vSphere Cluster become worker nodes and K8s Control VMs/Master VMs will run on the top same vSphere cluster. In this cluster, user creates a namespace and triggers “vSphere Pods” to run container workloads using same “kubectl” CLI. (vSphere admin manages it)

Here is a blog post demonstrating how to automate Supervisor cluster configuration

Tanzu Kubernetes Cluster” (aka Guest cluster): This is upstream-compliant Kubernetes cluster, which runs on the top of “Supervisor cluster” under the “namespace” created in Supervisor layer. This cluster uses open source Cluster API for life-cycle management (Devloper/DevOps manages it from familiar kubectl itself)

As usual I enjoy exploring new APIs got introduced as part of new vSphere release . In this post, my focus is on REST APIs exposed to manage life-cycle of ” Supervisor cluster”. As I run through vCenter API explorer (H5C -> Menu -> Devloper center -> API Explorer), I see this release has more REST APIs compared to SOAP APIs unlike any earlier vSphere releases. You can refer REST API documentation here as well. In this post, I will introduce you to new APIs got exposed as part of Supervisor cluster. I am pleased to see that 100% of the APIs are REST based. How cool is that !

First things to note that “API-endpoint” to call these APIs is “vCenter server”. i.e. we will be calling Supervisor cluster APIs against vCenter server.

Lets take look at below screenshot for how these APIs look like.

As you can see these APIs are identified under name “namespace_management” and “namespaces”
namespace_management : APIs under this section help manage all the aspect of managing “Supervisor cluster”.
namespaces : APIs under this section help manage “namespaces” created on the top of Supervisor cluster. Tanzu Kubernetes clusters are also created under namespaces created in Supervisor layer.

Most critical APIs are under “namespace_management/clusters ” section, where key APIs like enable/disable/update vSphere supervisor cluster are available. Below is how “enable” call looks like. i.e. configuring “Supervisor cluster”.
POST call
server : vCenter IP/FQDN and cluster:cluster MOID

Same above operations can be done from H5C UI ( Menu –> “Workload Management” )
I hope, at this stage you got basic idea on where to start exploring these APIs. In my next couple of posts, I will have deep dive into critical APIs to manage “Supervisor cluster” on given cluster i.e. “enable/disable/update” Ops. For now lets invoke one of the basic API calls to see something cool in action.

In my lab environment, I have 2 clusters in my vCenter server (in VCF term, 1 workload domain with 2 clusters), where “Supervisor cluster” is enabled on one and not enabled on second cluster. I chose to invoke an API, which gives us information on whether clusters in my vCenter inventory are compatible for enabling Supervisor cluster or not. As you know from my earlier posts this or this, this must be a GET call as follows


This is how you invoke it quickly from native API Explorer from within vSphere client (H5C)


Below is what I got the response, pasted as it is


[vcenter.namespace_management.cluster_compatibility.summary   {

},vcenter.namespace_management.cluster_compatibility.summary   {

  • “cluster”: “domain-c9”,
  • “compatible”: “true”,
  • “incompatibility_reasons”: [ ][]


As you see, my first cluster (moid: domain-c19) is not compatible and API gives us nice info on what are the basic requirements not met such as HA is not enabled, DRS is either not enabled or not in fully automated mode and new NSX-T VDS (aka conversed VDS) is not configured as well. How cool is that! As expected second cluster (moid: domain-c19) is perfectly fine as Supervisor cluster is already enabled there.

I hope you enjoyed my first post on this amazing innovation. Here is my new post on how to manage Supervisor cluster using DCLI. Please stay tuned for my detailed post on its cool functional aspects. Also, here is the official documentation on “vSphere with K8s” for your further learning. I enjoyed providing my candid feedback on various aspect of this documentation last month, I am sure you will love reading it.

Once again I would like to remind you that “vSphere with Kubernetes” is available through VCF and once you have VCF workload domain ready, you would be re-directed to vCenter H5C to proceed for further ops on managing/enabling vSphere with Kubernetes.

Further reading:
1. REST API documentation & my new post on automating Supervisor cluster configuration or Automating supervisor cluster workflows using Java SDK
2. How to get vSphere with Kubernetes?
3. vSphere with Kubernetes 101 is here
4. Introduction to manage vSphere Supervisor Cluster
5. Official documentation for vSphere with Kubernetes is here