Why you would want to execute tasks via the NSX API asynchronously is a good question, and, can be answered with two words “Parallel Workflows”. In a Software Defined Datacenter (SDDC) where automation is extensively used, it may be beneficial to execute tasks asynchronously so that your automation workflow can continue while a certain NSX logical construct is built (deployed), one such example is an Edge Services Gateway. This same framework also provides us the ability to query the status of the job to verify if it has been successful or not, which can be quite important if you need to check if a logical component is configured or not.
To show an example of such a use case, let’s use the Mozilla Firefox REST Client to submit a job to NSX-v Manager and retrieve the status of a Job by querying the Job ID.
The job we will be submitting, is to configure a host-based route on an existing Edge Services Gateway, but the same principle applies when submitting any job to the end of any 4.0 service configuration URL (consult the NSX API guide for further information).
So the URL we will be submitting to is:
- 172.16.32.240 is the IP Address of the NSX-v Manager in the InfoTech Lab
- edge-9 is the Edge ID of the ESG, I want to configure.
Note: The most important thing that you need to do for the job to be submitted asynchronously, is to include the suffix ?async=true to the end of your REST call.
So let’s submit the following XML to NSX Manager via REST from the Firefox REST Client for this demonstration; of course, we could be scripting this.
<staticRouting> <staticRoutes> <route> <description>route1</description> <vnic>0</vnic> <network>126.96.36.199/32</network> <nextHop>172.16.32.254<nextHop> <mtu>1500</mtu> </route> </staticRoutes> </staticRouting>
The following snippet shows the REST Client prior sending the XML:
After the REST PUT CALL has been sent you will receive the following Response Headers back:
What we see here are two valuable pieces of information, which are:
- Status Code
The status code we receive back is 202 Accepted as opposed to 201 Created which is what we normally get back when submitting jobs. 202 Accepted means that the service successfully accepted the request but does not say if it has been successfully implemented or not. In addition to Status Code, you also receive the Location, the location gives us the job-id parameter which we will use in the next request to retrieve the status of the job.
Retrieving status of submitted job, you need to use the following URL, replacing job-id with the jobID you received from the PUT request.
GET https://172.16.32.240/api/4.0/edges/jobs/jobdata-jobID GET https://172.16.32.240/api/4.0/edges/jobs/jobdata-1053
The following figure shows the submitted request to the NSX Manager.
This time, when looking at the Request Headers we see the status code of 200, which means the request was OK and returns XML in the body. So if we look at the request body you should see something similar to the following:
As you can see from the status field, the job was completed and if we now look at the NSX-v Edge via the vSphere Web Client, we indeed see the new static route exists.
The possible values for the status field in the XML are as follows:
Although the example in this blog post is fairly rudimentary, it should show the principles that can be leveraged when trying to automate many tasks as part of a SDDC workflow. Where some tasks can be submitted in parallel and others in serial, with checks put into the workflow to ensure that certain tasks have completed prior to continuing. How you will use this in your workflows is up to you, but making them efficient and with error checking should be a consideration of any good automation workflow.