#VMware has ended active development of this project, this repository will no longer be updated.

#nsxramlclient

This Python based client for NSX for vSphere 6.x gets its API structure information (e.g. URLs, parameters, schema, etc.) from a RAML file which describes the NSX for vSphere REST API. It has been developed and tested for use with VMware NSX for vSphere 6.x.

The latest version of the NSX for vSphere 6.x RAML file can be found at http://github.com/vmware/nsxraml

NOTE:

Please read the bellow Version information. The 2.0 Version of nsxramlclient is needed to support the new format of the nsxraml spec on http://github.com/vmware/nsxraml that introduced a breaking change in the way schemas are handled. If you are using the 1.x version of nsxramlclient you will need to use the 6.1.4, 6.1.6 or 6.2.2 versions of the nsx raml spec. In the 2.0 version the method extract_resource_body_schema was replaced with extract_resource_body_example

Also, in the NSXv 6.3 version of the nsx raml spec XML Comments and pre-filled content was introduced in the RAML spec to improve readability of the created HTML and PDF artifacts. This change may break existing code, so version 2.0.6 of the nsxramlclient now removes any XML comments and pre-filled content.

Version History

Version 2.0.7

NSX-v 6.4 introduced a new response code 202 for the controller creation API (Issue [#22]). This version of nsxramlclient accepts 202 as a successful response code

Version 2.0.6

This version of the nsxramlclient will now delete any XML comments found in the body content examples in the nsxraml spec. Previously nsxramlclient ran into a traceback if XML comments were used. Also, in this version nsxramlclient by default will remove all pre-filled content in the body content examples. This is needed because of a change in the nsxraml spec where the focus is now more shifting towards documentation, and pre-filled content helps in terms of readability in the examples. This behaviour can be controlled by using the remove_content= parameter in the extract_resource_body_example method.

Version 2.0.5

Added fail_mode='' option in NsxClient to raise an exception instead of sys.exit when setting fail_mode='raise', or continue without an exception if set to fail_mode='continue'. Default is still fail_mode='exit' to preserve backwards compatibility. Read the changed 'Create a session object' section for mode details

Version 2.0.3

Change in the dependencies to include 'oyopenssl' to make nsxramlclient easier to install on Windows

Version 2.0.2

Change in the lxml dependency. We are now mandating lxml 3.6.0 or lower because of installation issues seen on Windows with lxml 3.6.1.

Version 2.0.1

This version of nsxramlclient added support for repeating keys in the XML body without nested structure bellow. Before v2.0.1 nsxramlclient only supports repeating keys in the XML body if these repeating key themself hold multiple keys bellow them (nesting). This patch adds the support for repeating keys that only hold a values bellow them and no nested structure. This was needed to support the API call to create secondary IP Addresses on ESG router interfaces

Version 2.0

This version of nsxramlclient is needed to support the new format of the nsxraml spec on http://github.com/vmware/nsxraml that introduced a breaking change in the way schemas are handled. In the new NSX-v RAML spec schemas are now real schemas that can be used to check the correctness of your XML document. In the earlier versions the schema was used to return an XML example as a python Dict. The new way of retrieving the XML example dict is by using the new method introduced in the 2.0 version named extract_resource_body_example

Version 1.0.4

This release introduces new helper methods:

read_all_pages: This Method reads all pages from the API Get for the ['virtualWires', 'pagedEdgeList'] displayNames. This e.g. helps to collect all logical switches present in the system without having to know the needed page file size

normalize_list_return: There are API calls in NSX-v were you are getting a None object if no Object is present, a Dict type when only one Object is present, and a List of Dicts when more than one Object is present. E.g. for the retrieval of logical switches. When passing the API return to this function it will normalize the return to be a list. If the input is a None Object (no Object exists in NSX-v) an empty list is return. When one Object is found, a List with the one Dict is returned, when the input is a list, it is returned back unmodified

Version 1.0.2 and 1.0.1

Initial versions

How to install nsxramlclient

The following install instructions are based on Ubuntu 14.04 LTS, but installations on other Linux distributions or on the Apple MacOS should be relatively similar and should be familiar to those familiar with Python.

Check whether pip is installed

pip --version

If pip is not installed, install it with apt-get or the package manager appropriate for your operating system.

sudo apt-get update
sudo apt-get -y install python-pip

Now you can use pip to install the nsx raml client

sudo pip install nsxramlclient

In some cases the installation may fail because of missing dependencies. You may see the following message and will have to install the required packages

ERROR: /bin/sh: 1: xslt-config: not found
** make sure the development packages of libxml2 and libxslt are installed **

This example shows installing the dependencies using the apt package manager and the apt-get command. Once dependencies are installed you can retry the pip installation of the nsxramlclient shown above.

sudo apt-get install build-essential libssl-dev libffi-dev libxml2-dev libxslt-dev python-dev zlib1g-dev

Also sometimes you might run into the issue of missing Python OpenSSL on your Ubuntu machine. In this case you will see the following error message when importing nsxramlclient.client:

ImportError: No module named OpenSSL.SSL

if you encounter this, simply install the package python-openssl manually:

sudo apt-get install python-openssl

Examples on how to use nsxramlclient

Create a session object

It is required to create a session object with which you will interact with the NSX REST API. This session object will then expose the create, read, update and delete (CRUD) methods of each NSX object as well as some helper methods that will be useful.

from nsxramlclient.client import NsxClient

nsxraml_file = '/raml/nsxraml/nsxvapiv614.raml'
nsxmanager = 'nsxmanager.invalid.org'
nsx_username = 'admin'
nsx_password = 'vmware'

client_session = NsxClient(nsxraml_file, nsxmanager, nsx_username,
                           nsx_password, debug=False, fail_mode='raise')

The NsxClient class has the following initialization parameters:

"""
:param raml_file:
This mandatory parameter is the RAML file used as the basis of all URL
compositions. It allows the client to extract the body schema and convert the schema into python dictionaries.

:param nsxmanager:
This mandatory parameter is either the hostname or IP Address of the NSX Manager appliance.

:param nsx_username:
This mandatory parameter is the username on NSX Manager used for authentication to the NSX REST API running on the NSX Manager.

:param nsx_password:
This mandatory parameter is the password of the user used for authentication to the NSX REST API running on the NSX Manager.

:param debug: Optional:
If set to True, the client will print extensive HTTP session information to stdout.
Default: False

:param verify: Optional:
If set to True, the client will strictly verify the certificate passed by NSX Manager. It is recommmended in all production environments to use signed certificates for the NSX REST API. Please refer to the NSX for vSphere documentation for information on how to convert from the self-signed certificate to a signed certificate.
Default: False

:param suppress_warnings: Optional:
If set to True, the client will print out a warning if NSX Manager uses a self signed certificate.
Default: True

:param fail_mode: Optional:
If not set, the client will exit using sys.exit when receiving any error status code from NSX like 400.
If fail_mode is set to 'raise', the exception nsxramlclient.exceptions.NsxError will be raised with status
being the HTTP status code received and msg being the error message returned by NSX in the body. If set to
'continue', no error will be raised, and the status and body is returned like in successful cases.
Default: 'exit'

:return: Returns a NsxClient Session Object
"""

After you initialized a session object you have access to the following methods:

• create: Sends a HTTP POST to NSX Manager. More details will follow later in this readme.

• read: Sends a HTTP GET to NSX Manager

• update: Sends a HTTP PUT to NSX Manager

• delete: Sends a HTTP DELETE to NSX Manager

• view_response: Each of the above methods returns a Python OrderedDictionary with the HTTP Status code, location header, NSX Object Id, eTag Header and Body. This method outputs the OrderedDict in human readable text to stdout.

• extract_resource_body_schema: DEPRECATION WARING: Use the method extract_resource_body_schema. In future version this will be removed This method will retrieve the body schema from the RAML File (if the method has a body schema like most create methods), and will return a template python dictionary that can be used to construct subsequent API calls.

• extract_resource_body_example: This method will retrieve the body example from the RAML File (if the method has a body example like most create methods), and will return a template python dictionary that can be used to construct subsequent API calls.

• view_resource_body_schema: This method retrieves the body schema from the RAML file and outputs it to stdout as a pretty printed XML document.

• view_resource