Feedback
Table Of Contents
About Cisco UCS Manager XML API
Unified Computing System Overview
Cisco UCS Management Information Model
Capturing XML Interchange Between the GUI and the Cisco UCS
Cisco UCS Manager XML API
This chapter includes the following:
•
About Cisco UCS Manager XML API
•
•
•
About Cisco UCS Manager XML API
The Cisco UCS Manager XML API is a programmatic interface to the Cisco Unified Computing System. The API accepts XML documents through HTTP or HTTPS. Developers can use any programming language to generate XML documents that contain the API methods. Configuration and state information of the Cisco UCS is stored in a hierarchical tree structure known as the management information tree, which is completely accessible through the XML API.
The API model is recursively driven and provides major functionality for application development. For example, changes can be made on a single object, an object subtree, or the entire object tree. With a single API call, changes can be made to a single attribute of an object, or to the entire Cisco UCS structure, including the configuration of chassis, blades, adapters, polices, and most other hardware and software components.
The API operates in forgiving mode. Missing attributes are substituted with default values (if applicable) that are maintained in the internal data management engine (DME). The DME ignores incorrect attributes. If multiple managed objects (MOs) are being configured (for example, virtual NICs), and any of the MOs cannot be configured, the API stops its operation. It returns the configuration to its prior state, stops the API operation that listens for API requests, and sends a fault notification.
The API leverages an asynchronous operations model to improve scalability and performance. Slower API processes are nonblocking so that faster processes can proceed. A process receives a success message upon a valid request, and a complete message when the task is finished.
Full event subscription is enabled. After subscribing, any event notification is sent along with its type of state change.
Updates to MOs and properties conform to the existing object model, ensuring backward compatibility. If existing properties are changed during a product upgrade, they are managed during the database load after the upgrade. New properties are assigned default values.
Operation of the API is transactional and terminates on a single data model. Cisco UCS is responsible for all endpoint communication, such as state updates; users cannot communicate directly to endpoints. In this way, developers are relieved from the task of administering isolated, individual component configurations.
The API model includes the following programmatic entities:
•
•
•
A typical request comes into the DME and is placed in the transactor queue in FIFO order. The transactor gets the request from the queue, interprets the request, and performs an authorization check. After the request is confirmed, the transactor updates the management information tree. This complete operation is done in a single transaction.
Unified Computing System Overview
A Cisco UCS unit can consist of up to two Cisco UCS fabric interconnects and a minimum of one Cisco chassis with one blade or rack-mounted server. Up to 40 chassis with a mixture of blade and rack-mounted servers can be connected and controlled by a single Cisco UCS Manager instance.
Cisco UCS Manager runs on the primary fabric interconnect, with failover capability to the subordinate fabric interconnect. In the event of a failover, the virtual IP address will connect to the subordinate fabric interconnect, making it the new primary fabric interconnect.
All XML requests to the Cisco UCS are asynchronous and terminate on the active Cisco UCS Manager. Cisco UCS Manager mediates all communication within the system; no direct user access to the Cisco UCS components is required.
Cisco UCS Manager is aware of the current configuration and performs automated device discovery whenever a new resource is installed. After a resource is detected, the Cisco UCS Manager adds it and its characteristics to the system inventory. Cisco UCS Manager can preconfigure the new resources if it is directed to do so by an administrator-defined policy.
Cisco UCS Management Information Model
All the physical and logical components that comprise Cisco UCS are represented in a hierarchical management information model, referred to as the management information tree. Each node in the tree represents a managed object (MO) or group of objects that contains its administrative state and its operational state.
The hierarchical structure starts at the top (sys) and contains parent and child nodes. Each node in this tree is a managed object and each object in Cisco UCS has a unique distinguished name (DN) that describes the object and its place in the tree. Managed objects are abstractions of the Cisco UCS resources, such as fabric interconnects, chassis, blades, and rack-mounted servers.
Configuration policies are the majority of the policies in the system and describe the configurations of different Cisco UCS components. Policies determine how the system behaves under specific circumstances. Certain managed objects are not created by users, but are automatically created by the Cisco UCS, for example, power supply objects and fan objects. By invoking the API, you are reading and writing objects to the management information model (MIM).
The information model is centrally stored and managed by the data management engine (DME), a user-level process running on the fabric interconnects. When a user initiates an administrative change to a Cisco UCS component (for example, applying a service profile to a server), the DME first applies that change to the information model, and then applies the change to the actual managed endpoint. This approach is called a model-driven framework.
Figure 1-1 is a branch diagram starting at sys from topRoot of the Cisco UCS management information tree. The diagram consists of five populated chassis with eight blades in each chassis, and each of the blades has one or more adapters. For simplicity, only chassis number five is expanded.
Figure 1-1 Illustration of MIN Structure Showing Five Chassis
Tree (topRoot):—————————————-Distinguished Name:|——sys———————————--- (sys)|——chassis-1————————(sys/chassis-1)|——chassis-2————————(sys/chassis-2)|——chassis-3————————(sys/chassis-3)|——chassis-4————————(sys/chassis-4)|——chassis-5————————(sys/chassis-5)|——blade-1————— (sys/chassis-5/blade-1)|——adaptor-1—- (sys/chassis-5/blade-1/adaptor-1)|——blade-2————— (sys/chassis-5/blade-2)|——adaptor-1—- (sys/chassis-5/blade-2/adaptor-1)|——adaptor-2—- (sys/chassis-5/blade-2/adaptor-2)|——blade-3————— (sys/chassis-5/blade-3)|——adaptor-1—- (sys/chassis-5/blade-3/adaptor-1)|——adaptor-2—- (sys/chassis-5/blade-3/adaptor-2)|——blade-4————— (sys/chassis-5/blade-4)|——adaptor-1—- (sys/chassis-5/blade-4/adaptor-1)|——blade-5————— (sys/chassis-5/blade-5)|——adaptor-1—- (sys/chassis-5/blade-5/adaptor-1)|——adaptor-2—- (sys/chassis-5/blade-5/adaptor-2)|——blade-6————— (sys/chassis-5/blade-6)|——adaptor-1—- (sys/chassis-5/blade-6/adaptor-1)|——blade-7————— (sys/chassis-5/blade-7)|——adaptor-1—- (sys/chassis-5/blade-7/adaptor-1)|——blade-8————— (sys/chassis-5/blade-8)|——adaptor-1—- (sys/chassis-5/blade-8/adaptor-1)
Cisco UCS XML API Sample Flow
A typical request comes into the data management engine (DME) and is placed in the transactor queue in FIFO order. The transactor gets the request from the queue, interprets the request, and performs an authorization check. After the request is confirmed, the transactor updates the management information tree. This operation is done in a single transaction.
Figure 1-2 shows how Cisco UCS Manager processes a boot server request.
Table 1-1 describes the steps involved in a boot server request.
Figure 1-2 Sample Flow of Boot Server Request
Object Naming
You can identify a specific object by its distinguished name (DN) or by its relative name (RN).
This section contains the following topics:
Distinguished Name
The distinguished name enables you to unambiguously identify a target object. The distinguished name has the following format consisting of a series of relative names:
dn = {rn}/{rn}/{rn}/{rn}...In the following example, the DN provides a fully qualified path for adaptor-1 from the top of the object tree to the object. The DN specifies the exact managed object on which the API call is operating.
< dn ="sys/chassis-5/blade-2/adaptor-1" />Relative Name
The relative name identifies an object within the context of its parent object. The distinguished name is composed of a sequence of relative names.
For example, this distinguished name:
<dn = "sys/chassis-5/blade-2/adaptor-1/host-eth-2"/>is composed of the following relative names:
topSystem MO: rn="sys"equipmentChassis MO: rn="chassis-<id>"computeBlade MO: rn ="blade-<slotId>"adaptorUnit MO: rn="adaptor-<id>"adaptorHostEthIf MO: rn="host-eth-<id>"API Method Categories
Each method corresponds to an XML document.
This section contains the following topics:
•
Note
Authentication Methods
Authentication methods authenticate and maintain the session. For example:
•
•
•
Authentication methods initiate and maintain an active session. A successful authentication must be performed before other API calls are allowed. API requests are cookie authenticated.
Use the aaaLogin method to get a valid cookie. Use aaaRefresh to maintain the session and keep the cookie active. Use the aaaLogout method to terminate the session (also invalidates the cookie). A maximum of 256 sessions to the Cisco UCS can be opened at any one time.
Operations are performed using the HTTP post method (Cisco UCS supports both HTTP and HTTPS requests) over TCP. HTTP and HTTPS can be configured to use different port numbers, but TCP/80 (or TCP/443 for secure connections) is used by default. The HTTP envelope contains the XML configuration.
Note
After a connection is established and authenticated, a cookie is returned in the response. The cookie is valid for 7200 seconds (120 minutes), and must be refreshed during the session period to prevent it from expiring. Each refresh operation creates a cookie valid for the default interval.
Query Methods
Query methods obtain information on the current configuration state of an object. The following are query examples:
•
•
•
•
•
•
•
•
Most query methods have the argument inHierarchical (Boolean true/yes or false/no). If true, the inHierarchical argument returns all child objects.
<configResolveDn ... inHierarchical="false"></><configResolveDn ... inHierarchical="true"></>The query API methods might also have an inRecursive argument to specify whether the call should be recursive (for example, follow objects that point back to other objects or the parent object).
Query Filters
The API provides a set of filters to increase the usefulness of the query methods. These filters can be passed as part of a query and are used to identify the wanted result set.
This section contains the following topics:
Simple Filters
There are two simple filters, the true filter and false filter. These two filters react to the simple states of true or false, respectively.
•
•
Property Filters
The property filters use the values of an object's properties as the criteria for inclusion in a result set. To create most property filters, classId and propertyId of the target object/property is required, along with a value for comparison.
•
•
•
•
•
•
•
•
•
Composite Filters
The composite filters are composed of two or more component filters. They enable greater flexibility in creating result sets. For example, a composite filter could restrict the result set to only those objects that were accepted by at least one of the contained filters.
•
•
•
•
Modifier Filter
A modifier filter changes the results of a contained filter.
•
This is the only modifier filter that is supported.
Configuration Methods
There are several methods to make configuration changes to managed objects. These changes can be applied to the whole tree, a subtree, or an individual object. The following are examples of configuration methods:
•
•
•
Most configuration methods use the argument inHierarchical (Boolean true/yes or false/no). These values do not play a significant role during configuration because child objects are included in the XML document and the DME operates in the forgiving mode.
Event Subscription Methods
When an object is created, changed, or deleted because of a user- or system-initiated action, an event is generated. Applications get state change information by regular polling or event subscription. Because polling is resource-expensive, event subscription is the prefered method of notification.
On an event that has a subscription, Cisco UCS notifies the client and the type of event. Only actual change events are sent, not the object's unaffected attributes. This applies to all object changes in the system.
Every time an object is created, changed, or deleted because of a user-initiated or system-initiated action, an event is generated. Applications can get state change information by either of the following options:
•
•
With subscription, when an event occurs, Cisco UCS sends a notice that contains only changed data. Notification can be sent for all object changes in the system. Use eventSubscribe to register for events, as shown the following example of subscriptions:
<eventSubscribecookie="<real_cookie>"></eventSubscribe>To receive notifications, open an HTTP or HTTPS session over TCP and keep the session open. On sending eventSubscribe, Cisco UCS starts sending all new events as they occur.
Each event has a unique event ID. Event IDs operate as counters and are included in all method responses. When an event is generated, the event ID counter increments and is assigned as the new event ID. This sequential numbering enables tracking of events and ensures that no event is missed. If the client detects a missing event ID, the client can use eventSendEvent to retrieve the missed event.
Capturing XML Interchange Between the GUI and the Cisco UCS
Interchange is stored in a log file such as C:\Documents and Settings\username\Application Data\Sun\Java\Deployment\log\.ucsm. Due to internal security requirements, this information is not always complete. However, you can use a commercial packet analyzer application to observe sent XML.
Success or Failure Response
Cisco UCS responds almost immediately to any API request. The response indicates failure if the request is impossible to complete. A successful response indicates that the request is valid, but not that the operation is complete. For example, it may take some time for a server to finish a power-on request. The power state changes from down to up only after the server actually powers on.
This section contains the following topics:
Successful Response
When a request has executed successfully, Cisco UCS returns an XML document with the information requested or a confirmation that the changes were made. The following is an example of a configResolveDn query on the distinguished name sys/chassis-1/blade-1:
<configResolveDndn="sys/chassis-1/blade-1"cookie="<real_cookie>"inHierarchical="false"/>The response includes the following information:
<configResolveDn dn="sys/chassis-1/blade-1"cookie="<real_cookie>"response="yes"><outConfig><computeItem adminPower="policy"adminState="in-service"assignedToDn=""association="none"availability="available"chassisId="1"checkPoint="discovered"connPath="A"connStatus="A"discovery="complete"dn="sys/chassis-1/blade-1"fltAggr="0"fsmDescr=""fsmFlags=""fsmPrev="DiscoverSuccess"fsmRmtInvErrCode="unspecified"fsmRmtInvErrDescr=""fsmRmtInvRslt=""fsmStageDescr=""fsmStamp="2008-11-24T01:27:10"fsmStatus="nop"fsmTry="0"lc="discovered"managingInst="A"model="Gooding"name=""numOfAdaptors="1"numOfCores="4"numOfEthHostIfs="2"numOfFcHostIfs="2"numOfThreads="0"operPower="off"operState="unassociated"operability="operable"originalUuid="1b4e28ba-2fa1-11d2-0101-b9a761bde3fb"presence="equipped"revision=""serial="1-1"slotId="1"totalMemory="4096"uuid=""vendor="Cisco"/></outConfig></configResolveDn>Failed Requests
The response to a failed request includes XML attributes for errorCode and errorDescr. The following is an example of a response to a failed request:
<configConfMo dn="fabric/server"cookie="<real_cookie>"response="yes"errorCode="103"invocationResult="unidentified-fail"errorDescr="can't create; object already exists."></configConfMo>Empty Results
A query request for a nonexistent object is not treated as a failure by the DME. If the object does not exist, Cisco UCS returns a success message, but the XML document contains an empty data field (<outConfig> </outConfig>) to indicate that the requested object was not found. The following example shows the response to an attempt to resolve the distinguished name on a nonexistent blade-4711:
<configResolveDndn="sys/chassis-1/blade-4711"cookie="<real_cookie>"response="yes"><outConfig></outConfig></configResolveDn>
