NSX-v: ESG – submitting tasks via the API Asynchronously

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:

PUT https://172.16.32.240/api/4.0/edges/edge-9/routing/config/static?async=true
  • 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>1.1.1.1/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:

ESG Async #1

After the REST PUT CALL has been sent you will receive the following Response Headers back:

ESG Async #2

What we see here are two valuable pieces of information, which are:

  • Status Code
  • Location

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.

ESG Async #3

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:

ESG Async #4

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.

ESG Async #5

The possible values for the status field in the XML are as follows:

  • SUCCESS
  • FAILED
  • QUEUED
  • RUNNING
  • ROLLBACK

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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s