Consuming the VMware NSX API

Using the NSX API as a consumption layer

VMware’s Software Defined Networking (SDN) solution NSX is architecturally separated in different planes: the management plane, the control plane and the data plane. Right at the top of these three planes sits the consumption layer of NSX. This can be the vSphere Client GUI, a Cloud Management solution such as vRealize Automation or any other platform or solution leveraging the NSX RESTful API. The NSX API is exposed at the Management Plane of NSX, or in other words by NSX Manager, and abstracts all underlying NSX services.

Getting familiar using the API

In a recent NSX Micro-segmentation project, I had to do some basic automation stuff with NSX. While I fundamentally understand the concepts of automation and orchestration, I am completely new to automating stuff myself. I have no recent background in coding or developing so using the NSX API to ‘get stuff done in NSX’ was pretty intimidating to me.

I also leveraged PowerNSX by the way, which is arguably more approachable but I stumbled across some pretty cool NSX API stuff I would like to share (and document for myself for future reference).

VMware Project Platypus

Being completely new to the NSX API the 500+ pages thick NSX API Guide was largely abracadabra to me when I first opened it. While doing some pre-engagement research, I came across a very cool initiative that helped me enormously: Project Platypus by Grant Orchard. This is a ‘Swagger-based documentation’ solution for VMware’s REST API’s, including NSX. You can download it containerized in a handy Docker container at GitHub and use your web browser to explore the API:

Deployment of Platypus is very straightforward and documented at the GitHub project page. I will not go into specific details here. Even easier, Martijn Smit hosts the Swagger UI at http://vmwareapis.com/ and checks for updates every night. If you have an Internet connection this is the quickest and easiest way to use Platypus.

Looking up Managed Object References in vCenter Server

For many API calls, you have to specify a contextID. For example, if you want to retrieve ‘flow details for a given context’ you have to specify the ‘ vc-moref-id of datacenter, port group, vm, or uuid of vNIC for which flow is to be retrieved’:

You can find these IDs by using the Managed Object Browser of vCenter Server. This service is exposed at https://<vcenterserver>/mob. You then have to browse to

• Content:

• rootFolder group-d1 (Datacenters):
• childEntitity datacenter:
  
• You can find the relevant object identifiers in the Value column.

To get back to my example: if I wanted to get flow details for my entire datacenter, the contextID would be: datacenter-2 in my case. More details about retrieving vCenter Object IDs can be found in Chapter 20 of the NSX API guide and VMware Knowledge Base article 10171026.

Creating an NSX CLI only user account

By default, only the NSX builtin Admin account has access to the API. From a security and audit trail perspective, you do not want people using this Admin account for privileged API access. Instead of rewriting what I learned from Dale Cohglan‘s blog about how to achieve this, I rather just link to his excellent blogpost containing a very detailed step by step explanation. Thanks Dale!

Putting it all together

Using a REST plugin in your webbrowser allows you to execute the appropriate API calls. I used the RESTclient plugin for Firefox. This is a simple, lightweight REST client thats fit for purpose for me. First you have to provide authentication details. Choose Authentication in the top menu and select Basic Authentication and provide your credentials:

You can now execute API requests using the information obtained from Platypus. The API call to retrieve all Security Tags from NSX Manager for example is GET https://<nsxmanager>/api/2.0/services/securitytags/tag. You can find all these details in Platypus:

Hit SEND and the NSX API will return all NSX Security Tags in the Response Body:

In conclusion

Well, that’s it. I guess this is all very, very basic stuff and we’re just toe dipping in the water here but I hope this introductory post helps another newbie like myself out someday! Good luck and if you have anything to add, correct or improve in this post … please reach out!