Introduction to UCS Python SDK Part III Cisco DevNet Learning Labs

Overview

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.

Objective

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

Prerequisites

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.

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

Reset-Ucs-LL Icon:



Reset-Ucs-LL Console:



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:

  len(blades)



There are several methods of printing from this variable to the screen.

  • Print the first computeBlade object using vars(blades[0])
  • Note: the numeral in brackets identifies an object (python lists and dicts start at 0)

    vars(blades[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)
    • filter_type:
      • 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:
      • not
      • and
      • or
    • flag

      • I - case insensitive
      • C - case sensitive - the default value
    • Examples:

      • filter_str="(usr_lbl, 'test', type='eq')"
      • filter_str="(dn,'org-root/ls-C1_B1', type='eq') or (name, 'event', type='re', flag='I')"