Home > Software Development, Virtualization > Cisco UCS Management APIs

Cisco UCS Management APIs

November 14th, 2011 Leave a comment Go to comments

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.

Key Concepts

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure

HTML5 App

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:

Authentication methods

  • aaaLogin—Initial method for logging in.
  • aaaRefresh—Refreshes the current authentication cookie.
  • aaaLogout—Exits the current session and deactivates the current authentication cookie.

Query methods

  • 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.

Configuration methods

  • 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.

Some Samples

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
http://developer.cisco.com/web/unifiedcomputing/pshell-download

Ruby API for the UCS API by Steve Chambers. https://github.com/UCSAPI/UCSAPI

UCS Automation Tool (goUCS)
http://developer.cisco.com/web/unifiedcomputing/goucs

Hold on, where is Java binding? Unfortunately I didn’t find one. Should you have any clue, just share it in comment.

Other Resources
UCS XML API “Hello World”, by John McDonough

UCS Lab Wiki.

goUCS and XML API

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.

  1. November 15th, 2011 at 07:43 | #1

    I use Groovy and HTTPBuilder for basic UCS operations, would love a proper Java API.

    Check out my examples on github:

    https://gist.github.com/1366970

    – Martin

  2. November 15th, 2011 at 11:20 | #2

    Thanks for sharing your work Martin! I agree that a Java API would be helpful. Let me see if I can find time to get more familiar with the API and do something there.

    Steve

  3. shashank
    March 12th, 2014 at 15:41 | #3

    hai
    actually i am undergraduate student working on project by name private cloud management- cisco ucs can you help me with code please

  1. February 28th, 2015 at 13:38 | #1