If Cisco Unified Computing System (UCS) is a powerful V12 engine, then the UCS API is the clever engine CPU that make that big block dance.
Through the API you can get information about objects like blades, you can configure those objects such as turning them on/off, and you can listen for events. All of this is done with commands and responses coded in XML sent via HTTP POST to the ‘nuova’ application running on the primary fabric interconnect.
The success of the vSphere PowerCLI goes to show the incredible value that can be derived by providing a simple, open and free progammatic interface for powerful compute platforms to the community.
It’s nearly a year ago since I cracked the lid on the very simple how to access the UCS API with Ruby, and now I’ve done something a bit more usable by developing a UCSAPI gem that anyone can download and use easily. Let me first answer some obvious questions:
Why Ruby?
- It is universal: it runs on all platforms, not just Windows.
- It is simple: you can learn ruby in days just by using it, no training required.
- It is a cloud friendly language: EngineYard anyone?
Why do we need a Ruby interface to the XMLAPI interface?
- To interact with the “raw” UCS interface, you need HTTP and XML capabilities, and a knowledge of the API constructs. This is not easy for everyone and represents a learning curve that might put people off.
- Ruby is similar to PowerShell in that it uses objects, metaprogramming and reads naturally which makes it easier to learn than the raw UCS interface. Get there faster.
- The value is not in programming to the interface, but in developing uses for the interface such as “trending CPU temperatures” or “boot blade 3 with Hadoop instead of VDI between the hours of 7pm and 7am”. Ruby has modules for all kinds of great tools that can be simply combined with UCSAPI.
Justification over, here’s the how:
- If you haven’t got a real UCS system to test against (and why not?!) then go get the free Cisco UCS Platform Emulator.
- Then you need to get Ruby. I’ve been using the stable 1.8.7 release, but there’s a new 1.9.1 release out that I haven’t tested against. This is alpha code, ya know.
- With Ruby install, next you need to get the rubygems package manager. I install this as root (sudo make install).
- Now you have Gems you need to get the UCSAPI gem. Fastest way to do this, now that you have gems, is to ‘sudo gem install UCSAPI’. Dependencies will be installed for you.
- Get scriptin’! Use irb on the command line to do things interactively, a la Powershell, or put your code into a .rb file and run it.
Here’s an example of using the UCSAPI helper methods that wrap around XML API calls and hide the complexity. For example, the “fabric” method takes a few different parameters ( :dn, :id ) and will create the right XML API command, send it to UCS and get the response back to you in a friendly object format.
Last login: Thu Sep 30 21:52:06 on ttys001
13:20:08 ~ $ irb
>> require 'UCSAPI'
=> true
>> include UCSAPI
=> Object
>> ucspe = UCSM.new( :url => 'http://192.168.1.66/nuova', :inName => 'config', :inPassword => 'config')
...output removed..
>> ucspe.fabric
..dumps two fabric objects out, which look ugly on a blog...
>> ucspe.fabric.each { |fabric| puts fabric.oobIfIp }
192.168.1.66
0.0.0.0
>> ucspe.chassis.each { |chassis| puts chassis.dn + " is managed by Fabric " + chassis.managingInst }
sys/chassis-1 is managed by Fabric A
sys/chassis-2 is managed by Fabric A
sys/chassis-3 is managed by Fabric A
>> ucspe.fan( :fabric => 'A' ).each { |fan| puts fan.serial + " is " + fan.operState }
Chassis-2A is operable
Chassis-1A is operable
>> ucspe.psu( :chassis => 1).each { |psu| puts psu.dn + " voltage is " + psu.voltage }
sys/chassis-1/psu-4 voltage is ok
sys/chassis-1/psu-3 voltage is ok
sys/chassis-1/psu-2 voltage is ok
sys/chassis-1/psu-1 voltage is ok
This is just a very early first version and there’s much more to do. It’s probably too early to ask people to join in, but then again is there ever a good time… drop me a comment/email/tweet if you want to get involved.
Comments