Working with NSX – Deploying NSX Controllers via GUI and API

NSX Manager is used to deploy NSX Controllers for managing the control plane activities that take place within the environment. The controllers form a cluster, and like any good cluster will require a quorum (majority) in order to avoid any sort of split brain scenario. A quorum is best achieved with an odd number – such as 3 or 5 nodes – so that it can lose one or more nodes and continue to function as a cluster.

The NSX Controllers form a cluster with hardly any effort from your perspective. Each controller is deployed and configured by the NSX Manager – with your input, of course – and then join the cluster. By running a show command, we can see the status of the controller cluster from any of the member nodes.

show control-cluster status
Details on the controller cluster
Details on the controller cluster

The node above is reporting that it has joined the cluster successfully, is connected to the majority of the cluster (in this case, all nodes make up the majority), and it can be safely restarted without taking down the cluster majority and ruining the quorum. You can also read about the controllers from Scott Lowe’s NVP series here.

One of the key features of the controller cluster is that is uses slicing to distribute the control plane workload. Each service is “sliced” into smaller units of work and distributed among the controllers. If a controller is added, or fails, the slices can be redistributed. This ensures that no one controller owns any one service in particular, and that bottlenecks are avoided by distributing the slices of work. I’ve also heard this called “sprinkling” the slices. Fun vocabulary, no? 🙂

Adding a Controller via vSphere Web Client

We’re going to create a 3 controller cluster in this post. The first one, or controller-1, will be created by way of the vSphere Web Client’s NSX plug-in. Navigate to Networking & Security > Installation. Click the green add button to create a new cluster. The wizard will require the following information:

  • NSX Manager – the name or IP of the NSX Manager server.
  • Datacenter – the datacenter that will house the NSX Controller.
  • Cluster/Resource Pool – the cluster or resource pool that will house the NSX Controller.
  • Datastore – the datastore that will house the NSX Controller.
  • Host – an optional field for when you wish to deploy the NSX Controller to a specific host in the cluster or resource pool. You can leave it blank if desired.
  • Connect To – the network port group that the NSX Controller will use to communicate.
  • IP Pool – a special NSX IP Pool that is used to assign IP addresses to the controllers (we’ll come back to this one)
  • Password – the admin’s password on the controller VM

And here is the completed wizard:

The add new controller wizard
The add new controller wizard

After clicking OK, a new VM will be deployed. You can open the console and watch the deployment progress if you’re feeling adventurous.

Watching the console do fun, console-y things
Watching the console do fun, console-y things

After the status changes from Deploying to Normal, you’re good to go.

Say hello to the new controller in town
Say hello to the new controller in town

You might wonder where the NSX-Controllers IP Pool came from. I cheated and made it already, so let’s discuss how to create one and why it’s different from a standard IP Pool.

Creating an NSX IP Pool

IP Pools are commonly used in an NSX environment for assigning IP addresses to controllers and VXLAN Tunnel Endpoints (VTEPs). There’s no room for manually assigning IPs in the software defined data center (SDDC), and so you’ll want to leverage pools. As NSX deploys more controllers and VTEPs, it will withdraw IPs from the pool and give them to whatever it is that wanted an IP. It also tracks that IP and puts it back in the pool if the entity has been removed.

I would advise setting aside a range of addresses for NSX to avoid IP conflicts.

If you don’t have an IP Pool by the time you fire up the new controller wizard, that’s OK. One of the IP Pool options is to make a new one. You’ll need to know the following:

  • Name – what you’re going to call the pool.
  • Gateway – the default gateway for the pool’s subnet.
  • Prefix Length – the subnet mask’s binary length (sometimes referred to as CIDR notation).
  • Primary / Secondary DNS – Domain Name System servers, optional.
  • DNS Suffix – the domain’s suffix, also optional.
  • Static IP Pool – the list of IP addresses being assigned to the pool.

I went ahead and created a pool for my controllers. The completed wizard is below:

An NSX IP Pool being used for NSX Controllers
An NSX IP Pool being used for NSX Controllers

Keep in mind that you will not be able to see this pool from within vSphere. It is not a typical vCenter IP Pool. It lives only within NSX. If you need to view or edit the pool later, it can be found within the NSX Manager > Manage > Grouping Objects > IP Pools as shown below.

This is where the pools live
This is where the pools live

Querying NSX Manager via RESTful API

Ah, the fun part begins! Let’s throw some commands at NSX Manager and get it to do our nefarious bidding. I personally use the Advanced REST Client app within Chrome for fiddling around with the API (also known as debugging), but you can use whatever you wish.

There are a billion REST clients. Here are some suggestions:

Now that you have your REST client of choice, it’s time to generate your authorization string. This will be a Base 64 encoding of your credentials to NSX Manager. If you’re feeling especially lazy, and don’t mind that a 3rd party knows your encoding, you can just use the base64encode site.

Enter the string <user>:<password> where <user> is your NSX Manager user name and <password> is your password. If you haven’t made any accounts, just use admin:<password> for now.

Use the admin:password format for your encoding
Use the admin:password format for your encoding

The string generated here will be used to prove you are the admin and are allowed to make API calls to NSX Manager. Please don’t be a goofball and post it anywhere for people to see – the spongebob one above is obviously just an example that I don’t actually use. 🙂

The first API call we’re going to make is to query the current controllers. Use the following:

Request;GET https://nsx-manager-ip/api/2.0/vdn/controller
Header;Authorization: Basic YWRtaW46c3BvbmdlYm9i
Payload;

If you’re using the Advanced REST Client for Chrome, it will look like this:

A GET call to query the controllers in NSX
A GET call to query the controllers in NSX

Execute the query. You should get a response status of 200 (OK) along with response headers and XML data. There should be a bunch of data on controller-1 included in the XML, similar to what’s below:

The response XML contains a lot of data on the NSX Controller
The response XML contains a lot of data on the NSX Controller

At this point we know that NSX Manager is properly responding to our RESTful API request, and that controller-1 is properly being tracked. The next step is to issue a POST request that creates a brand new controller.

Create an NSX Controller with an API POST Request

While a GET request will query for existing data, a POST request will create something new. In this case, our POST request is going to create 2 new controllers (one at a time).

This time, we’ll need to supply a payload along with the POST request. The payload contents are very similar to what was requested in the vSphere Web Client, with some differences. Can you spot them?

The POST request will create a new controller
The POST request will create a new controller

There are two pretty big differences when making an API call vs the GUI. First, all of the XML fields require the ID, not the name, of the component. Such as “resgroup-10” for my Lab Cluster and “datastore-561” for my NAS2-VMs datastore. Additionally, you can specify the size of the NSX Controller via the API: small, medium, and large.

You can leverage the vCenter MOB (Managed Object) viewer to find the field IDs. Browse to https://<vcenter>/mob and log in with an account that has administrative privileges within vSphere. From there, click on Content > the rootFolder value link > the childEntity value link > any object you need an ID for. Here’s what mine looks like in the Wahl Network lab:

The MOB viewer
The MOB viewer

Once you have the IDs and have plugged them into the API call, click on the Send button. If you get a return Status of 201 “Created” – great! It’s working as expected. Pop on over to the vSphere environment and watch a new controller spin up.

Moar controllers!
Moar controllers!

After 10 or so minutes, the new controllers should show up with a status of Normal. Repeat the POST request to fire up a 3rd controller. Ignore the fact that my third controller is controller-6. I spent a lot of time building and destroying controllers.

The three amigos
The three amigos

That’s it! There is now a 3 node controller cluster for the NSX environment that will be used to handle control plane activities for the virtualized network. The next section focuses on Preparing The Cluster and Hosts.