I really like Ciscos UCS platform – what I don’t like is repeating work that I’ve done around 100 times and clicking through a 15 deep menu to do it. In general, I don’t have anything against the GUI as an interface, it has a time and a place such as getting a feel for the platform, its constructs and capabilities – especially if its something you are totally new to. However there comes a time when some things just don’t warrant the effort to manually do anymore – Am I really learning anything new? Can I speed this process up?
When I found out UCS Manager had an XML API I was interested in how I could use it to make my life easier and save myself some time / ensure configuration consistency. In the organization I worked for requests for new segments within the DC was a sporadic process – often sprung on you on a Friday afternoon with no regard for the IT change process, it just needed doing then and there.
Documentation on the API was fragmented and hard to come by – there was an SDK that required the UCS old Java fat-client and converted the java client transactions into python requests. Needless to say I gave this a wide birth and continued on my quest to get to grips with the API. The UCS Manager API can be accessed via https://ucsm/nuova . Nuova was a Cisco acquisition that eventually became Ciscos Data Centre product range – maybe the URL was left in as a tip of the hat to Nuova? yeah – I doubt it too. There is also a management tree explorer that can be accessed by navigating to https://ucsm/visore
Inital Authentication…
Authentication to the API works via a cookie – However, the initial authentication is performed via credential submission and a token is presented for use in all the subsequent API requests
The below sample shows the function “GENERATE_COOKIE” – I am returning 2 values from the function for the purposes of this write-up – just so you can see the raw response from the UCSM (auth.text – indicated in red)
In the headers we are specifying the content of the requests as XML – I have saved these headers in a variable as we will be using them in subsequent requests.
The xml variable is the actual XML we are sending to the API – I found this XML structure kicking around in the API developer guide.
We are passing the API response into a for loop and iterating through each XML attribute to find the attribute ‘outCookie’ and storing its value in the variable ‘cookie’ (indicated in green)
Subsequent Requests…
Now that we have authenticated to UCSM and have our cookie – we can use this cookie to perform authentication to configure UCS Managed Objects – each managed object is uniquely identified by a distinguished name or DN, UCS is split into a sort of hierarchical tree with with some Managed Objects having a parent/child relationship – using the visore explorer is the best way to get to grips with the hierarchical structure of UCS
Identifying the XML documents associated to the Managed Object you want to configure is a relatively simple process, once you know how – in the UCSM GUI you can right click an existing construct and identify its XML structure and attributes by clicking “Copy XML”. Below is an example of a VLAN – we can see its a member of the fabricVlan class, its DN, Vlan Number and Name. Once we know how the document is formed we can just take it, parameterise and fire it off to the API with our required values.
I have crafted a CONFIG_WORKER function that authors an XML document that is to be consumed by the UCSM API – what attributes to fire at the API is a bit of a hit and miss process in all honesty – I haven’t found any documentation that mandates what attributes are mandatory for each Class/Managed object (Thank god for UCS-PE, right?) I just went through an iterative process of trimming the fat out of the original XML until there was just enough for it to do what I needed it to do.
We are passing the previously requested cookie into the XML along with values for the vlan name and vlan_id.
The config worker function then posts the XML document to the UCSM API – printing the status-code for good measure – fingers crossed for 200 !
The full script is as below – our inputs are in the main function – we are looking to create vlan 400 and name it accordingly 😉
Lets run the script! – It returns a 200, everything is looking good!
Checking in the UCSM GUI it seems we have created our VLAN programmatically!
That’s it! – Simples right? – Obviously this was a simple demo but the concepts remain the same across the UCS platform – you could use the same script to add the VLAN to uplinks and even add to it a service profile, even configure multiple UCS deployements at the same time!
https://github.com/thecraigus/routedefault/blob/master/ucsvlandeploy.py
RouteDefault: Musings of a Network Engineer 