Cisco UCS Management APIs

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

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.

This entry was posted in Software Development, Virtualization and tagged , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

3 Comments

  1. Posted November 15, 2011 at 7:43 am | Permalink

    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. Posted November 15, 2011 at 11:20 am | Permalink

    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
    Posted March 12, 2014 at 3:41 pm | Permalink

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

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

  • NEED HELP?


    My consulting helps clients with virtualization and cloud computing, including VMware infrastructure automation and orchestration, vSphere management APIs, and deep product integration with hypervisors. Current training offerings include vSphere APIs training, vCenter Orchestrator training, and etc. Should you, or someone you know, need these consulting services or training, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.