Introduction to UCS Python SDK Part III Cisco DevNet Learning Labs
UCS Python SDK is a set of Python modules, each containing one or more classes, developed specifically to automate UCS Manager. UCS Python SDK is developed with PEP8 compliance and supports every Managed Object exposed by the UCS XML Model . A special function convert_to_ucs_python() enables automatic Python script generation from operations performed in the UCS Manager GUI. Use convert_to_ucs_python() to quickly script UCS tasks.
Cisco UCS is an Integrated Compute Infrastructure that has supported an XML API since its introduction. UCS Manager is the service that provides the XML API endpoint along with a graphical interface and a command line. The UCS components both physical and logical are represented as XML objects in a hierarchical Object Model format and can be manipulated via the XML API.
All UCS objects are described in an XML schema, this schema defines the objects their attributes and associated values. The schema is also used to generate more a significant amount of the UCS Manager Python SDK. Because a UCS component must be part of the Object Model to be part of the UCS system all components of UCS are always available via the XML API.
This Introduction to UCS Python Learning Lab will guide you through the use of UCS Python SDK to connect to a UCS Manager, perform queries with simple and complex filters against UCS Manager objects and disconnect from the UCS Manager. UCS Manager Objects are representations of pools, policies, other logical constructs and physical entities.
Completion time: 30 minutes
Prior to starting this learning lab it would be helpful to understand UCS Manager and the functionality that it provides to manage UCS compute environments.
An understanding of Python would also be helpful.
UCS Python SDK
UCS Python SDK is a library of python code that enables the retrieval and manipulation of UCS Manager managed objects. UCS Manager API interaction can be categorized into several distinct sections.
- Queries and Filters
- Configurations and Transactions
- Event Subscription
UCS Python SDK provides modules, classes and functions for all the categorizations of UCS Manager API interactions, along with functions that allow for the inspection of object metadata and object hierarchical containment.
UCS Python SDK Download and Documentation
UCS Python SDK is a community supported project, the code, documentation and samples, repositories are on github.com.
Event Infrastructure Utilization
If you are utilizing event provided infrastructure a script has been provided to reset the environment to pre-lab settings.
On the desktop Double-click the
Reset-Ucs-LL shortcut, provide the UCS Manager IP address that was assigned to you for the Learning Lab and hit Enter
Repeat this process for each assigned IP address, if you were assigned more than one.
Exercise 3a - Copy XML" from the UCSM GUI to to discover XML Class names
Another strategy for getting familiar with the UCS Model, is to discover the XML Class names for many of the objects visible in the GUI.
Next we will discover the XML Class for a UCS Blade, and perform some class queries, save to a variable, and print/parse the output.
In the UCS Manager GUI, you can right click on objects in the GUI, and select to "Copy XML". To view a server object's XML do the following.
- On the left pane navigate to the Equipment Tab
- Click the "+" to expand Chassis
- Click the "+" to expand Servers
- Click "Servers" to populate the right hand panel with compute blade servers.
- Click any server to select it.
Right-click on the selected server, select "Copy XML" to copy to the Windows Clipboard, and then paste to a new Notepad session:
The first reference at the top of the XML is the XML Class name for an object.
"computeBlade" is the XML Class for a UCS Blade Server
Exercise - 3b - Use Python to query Classes, save to variables, print and parse
Log back into the UCS Manager if necessary.
from ucsmsdk.ucshandle import UcsHandle handle = UcsHandle("<ucs-manger-ip>", "admin", "passsword") handle.login()
Execute the following command to query for all instances of the computeBlade XML Class and store in the variable "blades":
blades = handle.query_classid("computeBlade")
We can use the Python function,
len() to determine how many instances of computeBlade were found:
There are several methods of printing from this variable to the screen.
- Print the first computeBlade object using
Note: the numeral in brackets identifies an object (python lists and dicts start at 0)
You can also print specific properties of this object (or iterate through all the objects to identify certain properties).
Let’s view the Model, Serial and Distinguished Name of all objects in the "blades" variable:
for blade in blades: print blade.model,blade.serial,blade.dn
There are many properties you can extract – "total_memory", "num_of_cpus", admin_state, etc.
Exercise - 3c - Use a Simple Query Filter
Print the blade list again but this time add num_of_cpus to the print command.
for blade in blades: print blade.model,blade.serial,blade.dn,blade.num_of_cpus
Notice that the blade model UCSB-B420-M3 num_of_cpus value is 4, a filter could be specified as part of the Class ID query to only retrieve blades where the num_of_cpus is equal to 4.
blades = handle.query_classid("computeBlade", filter_str="(num_of_cpus, '4', type='eq')") for blade in blades: print blade.model,blade.serial,blade.dn,blade.num_of_cpus
Filters as defined by the documentation in the source
filter_str(str): query objects with specific property with specific value or pattern specifying value.
(property_name, "property_value, type="filter_type")
- property_name: Name of the Property
- property_value: Value of the property (str or regular expression)
- eq - equal to
- ne - not equal to
- ge - greater than or equal to
- gt - greater than
- le - less than or equal to
- lt - less than
- re - regular expression - the default value
- logical filter type:
- I - case insensitive
- C - case sensitive - the default value
- filter_str="(usr_lbl, 'test', type='eq')"
- filter_str="(dn,'org-root/ls-C1_B1', type='eq') or (name, 'event', type='re', flag='I')"