Utilize API and CLI Commands to Manage an NSX Deployment

 

Deploy and successfully authenticate an REST API client for NSX

 
Ah.. REST API… Representation State Transfer Application Programming Interface.. sounds easy right?! Well, it’s not that bad, essentially, you will make a call to NSX via HTTPS in JSON or XML format to perform certain tasks like creating a logical switch, creating a logical router, or deploying an NSX controller. In fact there are certain things that can be done via REST API that are not present in the GUI. I don’t think the VCIX-NV certification will have you go into too deep of a technical level, but I suggest familiarizing yourself with a REST API Client, creating or interacting with basic NSX objects and learning proper syntax and formatting as well as retrieving and analyzing configuration data with API calls.
 
There are a couple of popular REST API clients that you can use, the two most popular are Google Chrome: Postman and Mozilla Firefox Restclient. I will be using the Google Chrome’s postman.
 
If you would like documentation on the various API calls and functionality, please see the NSX API Guide. I will be referencing this guide continually through this post.
 
Step 1. Install the Postman – Restclient using the link above.
 
1
 
Step 2. Once the plugin is installed, click the Launch App button.
 
2
 
Step 3. Authenticate Postman to NSX by clicking on Basic Auth and adding in the NSX manager credentials and clicking Refresh headers
 
4
 
The most common types of tasks you will use with the REST Client are below.
 
GET Query an object to read information pertaining to NSX manager and it’s objects and components
 
POST Change NSX configuration and create objects or components
 
DELETE Delete NSX configuration, objects, or components
 
Note: In order for the REST client to work, I had to replace my NSX Manager certificate with a CA certificate as my default showed the hostname “localhost.” I wrote a post on how to accomplish this if you hit the same issue – NSX Manager SSL certificate replacement with CA. The error message I received was below.
 

Could not get any response
This seems to be like an error connecting to https://nsxmanager.vcloud.local/api/2.0/services/ssoconfig. The response status was 0.
Check out the W3C XMLHttpRequest Level 2 spec for more details about when this happens.

 

Construct and execute an API call using correct syntax and formatting

 
Step 4. Next to GET enter the API URL call that you would like to make. I picked a random request as there are so many to choose from in the documentation. In my case, the request for SSO configuration.
 
19
 
Step 5. Let’s try a couple more to see what other types of information we can get. How about query certificates since I just hit an issue with certificates.
 
20
 
Or even query my NSX Controller(s)
 
21
 
As you can see, there is a lot of information you can query, this isn’t even the tip of the iceberg. I suggest running through the API documentation to run the GET or query on a few different objects and once you are comfortable move on to creating objects.
 

Analyze, modify, and successfully retrieve configuration data using an existing API call

 
Step 6. In order to use the POST command we will need to add an additional Header with the value Content-Type and Value with the string application/xml as shown below.
 
22
 
Step 7. Let’s create some objects. First, something simple, like an IP Pool. Referencing the documentation, the request to POST is below (sorry it was split on two pages).
 
23
 
Step 8. Paste the URL POST Request from the documentation and change to POST
 
24
 
Step 9. Select the Raw button and paste in the Request Body
 
25
 
Step 10. Define your values, then click Send
 
27
 
You should get a response of the identifier of the object that was created as shown below. I am showing the full page with the URL, Post, Headers, Values, and xml data.
 
28
 
Step 11. Confirm the IP Pool was created. Note: You may need to refresh your Web Client.
 
29
 
I wanted to show one more POST that is much more advanced than the IP Pool creation. The IP Pool creation was simple because you didn’t need to specify any object IDs in any values that you assigned. For example, if you wanted to deploy an NSX controller, and you needed to specify the datastore, you couldn’t just put the datastore name, you would actually have to use the datastore identified which may be something like datastore-126. Let’s go through the deployment of an NSX Controller below.
 
Step 11. Change both the Request URL and the Request Body as per the documentation.
 
34
 
Step 11. Change both the Request URL and the Request Body as per the documentation.
 
Step 12. Define your values. This is where it get’s a bit tricky. As I mentioned before, certain API calls will need to reference identifiers of vCenter Server objects, rather than friendly names. The easiest way I found to get this information, is to log into the Managed Object Browser and follow VMware KB 1017126. It’s not too difficult, but you will want to memorize this, or the KB number as I believe you access to the VMware Knowledge Base during the test. You may also need to get NSX information through additional GET API calls, for example the IP Pool. On tip/trick that I found, is you can run a GET first on other controllers (or any objects) to find what hosts, datastores, etc they are living on by ID, so you can just copy that info from the GET into the POST, if you don’t mind it being deployed to the same host, datastore, resource pool, etc.
 
35
 
Step 11. Click Send once you have plugged in all of the values. Notice, the jobdata ID at the bottom to confirm it has started the process.
 
36
 
Step 12. Finally, confirm that the controller is Deploying!
 
37
 
You should be able to do anything through the REST API and I have only given you a few examples, some easy, some complex. I recommend to go through the deployment of each of the major components of NSX (Edge, DRL, Logical Switch, etc.) to ensure you have a good understanding of complex REST API syntax . Also I suggest familiarizing yourself with the NSX API document. I know I have mentioned it over and over, but it would be tough to memorize Request URLs and Request Body syntax. Instead, just know how to use the document as a reference, search it, and be able to find what you are looking for quickly. This document will be provided to you on the VCIX-NV exam, so use it if needed!
 

3 Comments

    • Sean Whitney -  November 3, 2015 - 11:17 am 322

      Good info, thanks Matt!

      Reply
  1. John -  June 10, 2016 - 2:35 pm 491

    Great post! Most people new to REST API’s get stuck on the authentication headers, so thank you for showing how easy they are to set.

    Reply

Leave A Comment

Your email address will not be published. Required fields are marked (required):

Back to Top