The UCS API is a goldmine of information and control for UCS. The Big 4 systems management companies are all integrating their enterprise software with UCS, especially our partners BMC, but that doesn't stop you from exploring the API yourself.
What's the point?
Why bother with the API? It gives you 'free' access to all objects: you can get their values, you can configure objects and you can listen for events. Just being able to get values means that you can:
- Collect data into tools such as RRDtool and start to graph the activity of the system over time.
- You can use tools like GraphViz to map the objects.
- You can write "Health Check" scripts that check configuration settings against best practices.
The use cases are many.
The following example took me a few hours to set up from scratch - so if I can do it, you can do it :-) The purpose of this example is to show you how to connect to the API and extract some values using Ruby. You could, of course, use any other language like Perl, Python etc. I chose Ruby because Gene Kim of Tripwire told me to :-)
You can also read about this procedure on my ViewYonder blog - VMware + Ubuntu + Ruby + REST + XML + Cisco UCS API
Set up
The purpose of this example is not to show you how to set these things up - Google is your friend :-) But here are some high-level details.
I run Ubuntu9 in a VMware Workstation virtual machine on my XP laptop. Inside Ubuntu9 I have Ruby 1.8 installed plus IRB (Interactive RuBy) with the following extra gems: rest-client and REXML.
My simple development method at this point is to run irb in one window, and have the script in another. As I code and test in irb I commit the code to the script window with copy and paste: that way, I am guaranteed that my script will work.
The doc you need is Cisco USC Manager XML API Programmer's Guide
Accessing the API
First the high-level steps, then the code itself, then the output. I have attached the script to this doc - remove the .png and you are left with a text .rb file :-)
- Load the required modules - rubygems, rest-client and REXML.
- Login to the API by using RestClient.post with a separate "initiate.xml" file that has the <aaaLogin> code from page 2-2 of the API Prog Guide.
- Use REXML to parse the response, then extract and store the cookie.
- Build and post a query for <computeBlades>.
- Use REXML and XPath query to parse the response and display a few selected fields.
Here's the code (see attached test.rb script - remove the .png and you are left with a text .rb file :-))
#!/usr/bin/ruby -v
#
# Steve Chambers rough'n'ready RUCS script (Ruby UCS)
# No error checking or anything clever, just plain
# code to demonstrate how easy this is
#
require 'rubygems' # rest_client is a GEM addon, so need this to use it
require 'rest_client' # hides all the hard stuff for connecting to RESTful service
require 'rexml/document' # makes XML work dead easy
include REXML # means I don't have to put REXML:: before every Document class
# Login to UCS
# initiate.xml is simply the <aaaLogin /> code from page 2-2 of the UCS API pdf
ucsResp = RestClient.post 'http://beltac/nuova', File.read('../xml/initiate.xml'), :content_type => 'text/xml'
# Create an XML doc and parse it, especially taking out the cookie.
ucsLoginDoc = Document.new(ucsResp)
ucsLoginRoot = ucsLoginDoc.root
ucsCookie = ucsLoginRoot.attributes['outCookie']
#
# Now we've got a session and a cookie, the UCS XML API is at our disposal!
#
# The UCS XML-API has a powerful query system, so let's see the blades
computeBladesXML = '<configResolveClass cookie="' + ucsCookie + '" inHierarchical="false" classId="computeBlade"/>'
ucsResp = RestClient.post 'http://beltac/nuova', computeBladesXML, :content_type => 'text/xml'
# Create an XML doc out of ucsResp and parse it for stuff
ucsBladesDoc = Document.new(ucsResp)
ucsBladesDoc.elements.each("configResolveClass/outConfigs/*") {
|blade|
bladeName = blade.attributes["dn"]
bladePower = blade.attributes["operPower"]
puts "Blade " + bladeName + " is currently powered " + bladePower
}
And here's the output:
stechamb@ubuntu:~/dev/ruby/scripts$ ./test.rb
ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]
Blade sys/chassis-2/blade-6 is currently powered on
Blade sys/chassis-1/blade-1 is currently powered off
Blade sys/chassis-1/blade-2 is currently powered on
Blade sys/chassis-2/blade-3 is currently powered on
Blade sys/chassis-2/blade-1 is currently powered off
Blade sys/chassis-2/blade-2 is currently powered off
Blade sys/chassis-2/blade-5 is currently powered off
Blade sys/chassis-2/blade-7 is currently powered off
Blade sys/chassis-2/blade-4 is currently powered off
Blade sys/chassis-2/blade-8 is currently powered off
Blade sys/chassis-1/blade-3 is currently powered off
Blade sys/chassis-1/blade-4 is currently powered off
Blade sys/chassis-1/blade-5 is currently powered off
Blade sys/chassis-1/blade-6 is currently powered off
Blade sys/chassis-1/blade-7 is currently powered off
Blade sys/chassis-1/blade-8 is currently powered off
Blade sys/chassis-4/blade-1 is currently powered off
Blade sys/chassis-3/blade-2 is currently powered off
Blade sys/chassis-3/blade-3 is currently powered off
Blade sys/chassis-3/blade-4 is currently powered off
Blade sys/chassis-3/blade-5 is currently powered off
Blade sys/chassis-3/blade-1 is currently powered off
Blade sys/chassis-3/blade-6 is currently powered off
Blade sys/chassis-4/blade-2 is currently powered off
