After installing the UCS emulator, I started to read and try UCS management APIs. I found the following two documents very helpful: Cisco UCS Manager API Management Information Model, and Cisco UCS Manager XML API Programmer’s Guide.
The key concepts of the APIs are pretty similar to VMware vSphere API. For example, it has managed objects which represent UCS resources like chassis, blades, fabric interconnects, etc. They contain administrative states and operational state.
The managed objects form the inventory tree. In UCS terms, it’s called management information tree. Given Cisco’s root in networking space, it should not be a surprise to see the strong influence from SNMP world. The following is a sample inventory tree I copied from the programmer’s guide.
Every management object is identified by a unique distinguished name (DN), i.e., sys/chassis-1/locator-led. The strings between “/” are called relative names (RN), which is unique among all children of its parent node. Note that the tree’s root is called topRoot, and not included in the DNs. If you are familiar with vSphere API, you can think of the DN as the inventory tree path.
If you view the Emulator Control Panel, you can easily find dn of a managed object from the Managed Object Browser (does it sound familiar to you? Check out the VMware MOB.)
API Method Overview
By invoking APIs, you read and write objects to the inventory tree of the management information model (MIM). Some writing may trigger certain operations as result.
Here is a list of API calls in four types:
- aaaLogin—Initial method for logging in.
- aaaRefresh—Refreshes the current authentication cookie.
- aaaLogout—Exits the current session and deactivates the current authentication cookie.
- configResolveDn—Retrieves objects by DN.
- configResolveDns—Retrieves objects by a set of DNs.
- configResolveClass—Retrieves objects of a given class.
- configResolveClasses—Retrieves objects of multiple classes.
- configFindDnsByClassId—Retrieves the DNs of a specified class.
- configResolveChildren—Retrieves the child objects of an object.
- configResolveParent—Retrieves the parent object of an object.
- configScope—Performs class queries on a DN in the management information tree.
- configConfMo—Affects a single subtree (for example, a DN).
- configConfMos—Affects multiple subtrees (for example, several DNs).
- configConfMoGroup—Makes the same configuration changes to multiple subtree structures (DNs) or managed objects.
Event Subscription Methods
- eventSubscribe — Subscribe change events. To receive event notifications, keep the HTTP/HTTPS session open. UCS sends all new events in the system.
It’s not that clear with the overview. The following are a few XML request samples included in the emulator that I found give better idea. Most of them are straight-forward enough that I don’t need to explain at all. If not, I will add a little comment.
Sample 1. Login request
<?xml version="1.0"?> <aaaLogin inPassword="admin" inName="admin"/>
Sample 2. Query for children of an adaptor of a blade
<?xml version="1.0"?> <configResolveChildren inHierarchical="false" inDn="sys-machine/chassis-1/blade-2/adaptor-1" cookie="1214933755/7bc19b1f-332e-40b5-9520-d75f72ed3da9" classId="adaptorHostEthIf"> </configResolveChildren>
Sample 3 Reset the power of a server
<?xml version="1.0"?> <configConfMos inHierarchical="no" cookie="2/10/2/24"> <inConfigs> <pair key="org-root/ls-testLS1/power"> <lsPower status="modified" state="hard-reset-immediate" dn="org-root/ls-testLS1/power"/> </pair> </inConfigs> </configConfMos>
Notice the <pair> tag. It’s just a simple container for the parameters because one can send multiple set of parameters for some operations. Also, the cookie seems having been modified becuase it’s not in the right format.
Sample 4 register for events
<eventSubscribe cookie="<real_cookie>"> </eventSubscribe>
If you need more samples, you can download it from the emulator Web GUI. On the left side tree, you can click on the “API Schema & Samples.” I didn’t find any schema file there but 18 XML sample requests. These samples requests seem not recorded as they are but modified afterwards.
Language Bindings and Tools
XML is nice but not really what we want while scripting and coding. I found several nice language bindings or command line tool:
UCS PowerShell Toolkit (PowerTool) and .NET SDK
Ruby API for the UCS API by Steve Chambers. https://github.com/UCSAPI/UCSAPI
UCS Automation Tool (goUCS)
Hold on, where is Java binding? Unfortunately I didn’t find one. Should you have any clue, just share it in comment.
UCS XML API “Hello World”, by John McDonough
Note: if you want to try beyond the emulator, you can request (see more on wiki page) from Cisco a hosted test bed backed by a real UCS. It sounds like a great service empowering the community, but I haven’t tried that. If you do, feel free to share your experience.