utilizing-the-data-model-reference-guide-for-ilo

Utilizing the data model reference guide for iLO

Introduction

Very often since the implementation of the Redfish standard in HPE ProLiant servers, I get questions similar to: “How do I get the value of this iLO parameter using Redfish?” or “How to set this BIOS parameter using Redfish”? Or “How do I configure this subsystem using Redfish”?

Those questions are raised from different kinds of system managers, taking care of one or several hundreds of servers, or from IT DevOps willing to implement quickly a high quality code solving those questions.

This article proposes a practical methodology to answer the above questions and then explains how systems managers can implement their preferred solution: quick and dirty using curl/wget/PowerShell tools, quick and clean with the iLO Rest Interface Tool (ilorest) or DevOps oriented using the Python ilorest library.

This article assumes the reader has a basic knowledge of REST APIs as well as the Redfish standard.

In this document, we mix the terms “Redfish” and “iLO RESTful API”; historically, HPE started to implement a proprietary iLO RESTful API before the publication of the Redfish 1.0 standard. ILO 4 version 2.30 is Redfish 1.0 conformant while remaining backward compatible with the existing RESTful API. More on this topic can be found in the Redfish API implementation on iLO RESTful API for HPE iLO 4 technical whitepaper.

Introducing the iLO RESTful API Data Model Reference Guide

The iLO RESTful API Data Model Reference Guide for iLO document is the starting point of all the solutions presented below. It contains the exhaustive list of properties that can be accessed (get or set) in modern ProLiant servers. It is published in HTML format for a quicker and better browsing experience.

At the time of writing this article, the Markdown/Slate version of this document is still under construction. Hence, we will use the html version.

Its companion document Managing Hewlett Packard Enterprise Servers with the RESTful API is worth to read as it gives a high level description of the iLO RESTful API and presents the different objects and schemas of the data model. It provides as well pseudo code leveraged in HPE’s iLO REST examples explained further down in this article.

How do I… with Redfish?

When the question “How do I get/set/modify this or that attribute with Redfish”, the first thing to do is to identify, from the iLO Graphical User Interface or from the UEFI/RBSU menus and sub-menus the keywords best characterizing this attribute.

As an example if we want to set the information related to the Administrator of a server, we find in the BIOS/ (RBSU) -> Server Asset Information -> Administrator Information menu the list of keywords: Administrator Name, Administrator Phone Number, Administrator E-mail Address and Administrator Other Information:

A quick search of one of them in the Data Model Reference Guide returns their definition and the possible operations they support (GET, PATCH).

Note the first line in the Description paragraph of those properties: This property is a member of HpBios Attributes.

Clicking on this link leads to the beginning of the paragraph listing/grouping all the HpBios Attributes. From there, and at the time of writing this article, you get the following paths to the Attributes:

/rest/v1/Systems/{item}/Bios and 
/rest/v1/Systems/{item}/Bios/Settings

As explained in the Managing HPE servers with the RESTful API, the first link allows only GET operations and second link allows GET and PATCH operations. Hence, on a simple rack mount server a quick and dirty solution to modify the Administrator name of the server is to send a PATCH operation toward /rest/v1/Systems/1/Bios/Settings with the ad hoc body. The OData-Type header in the following command transforms the request into a pure Redfish request although the URI starts with /rest:

curl --dump-header - --insecure -u ilo-user:password \
     --request PATCH \
     -H "OData-Version: 4.0 " \
     -H "Content-Type: application/json " \
     --data '{"AdminName": "NewName"}' \
     https://<ilo-IP>/rest/v1/Systems/1/Bios/Settings

Why dirty?

First, issuing such a request against a server containing multiple SoCs (System on Chip) in a single chassis (i.e. HPE Moonshot) will probably fail since the first SoC may be referenced as Systems/C1N1 instead of Systems/1 as for a common rack server. In other words this solution may not be suitable for each and every server in the datacenter.

Then, what will happen if the Bios schema changes in the future? What if it moves this attribute elsewhere in the resource tree…?

nhancing the solution with hprest

We can achieve the same property modification using the iLO Interface tool (hprest):

Host# hprest login <ilo-IP> -u username -p password --selector=HpBios.
Host# hprest set “AdminName=NewName”--commit

Using the hprest interface tool is a better alternative to curl/wget/PowerShell with hardcoded URIs; the main reason is because hprest uses Resource Types (--selector=HpBios.) instead of hardcoded URIs.

Resource Types are defined in the Managing HPE servers with the RESTful API document as: “Resources that have the same type follow the same schema definition”.

This concept of Resource Type is the foundation of the Redfish standard. Each and every property, in the model belongs to a specific Type mentioned in the Data Model reference guide with a sentence beginning with: “This property is a member of … “ as shown in the above picture.

The methodology for managing servers with hprest requires one more step compared to the one with curl/wget/PowerShell:

1. Identify keywords characterizing the chosen property in the UEFI menus or in the iLO 4 graphical User Interface.
2. Look for those keywords in the Data Model Reference Guide.
   3.Identify the corresponding Resource Type mentioned by the Data Model Reference Guide (i.e. HpBios)
   4.Find the matching Type in hprest:

Host# hprest login <ilo-IP> -u ilo-user -p password
Host# hprest types | grep -i bios
HpBios.1.2.0
HpBiosMapping.1.2.0

1. Select the desired Type and issue the get/list/set command:

Host# hprest select HpBios. 
Host# hprest list | grep -i admin
Host# hprest set “AdminName=NewName” --commit

Developing a Redfish application

HPE proposes a rich ecosystem for DevOps around its RESTful API and Redfish implementations. For Windows/PowerShell, the entry point is in the Microsoft PowerShell gallery (search for HPE). Other interesting projects are in GitHub.

In this section we will explain the methodology to use with a concrete problem to solve for writing a long term valid Redfish code. Then we’ll study one implementation in Python.

What is the problem?

The problem we’d like to solve in this paragraph is to retrieve the properties of all the Management Processors NICs of a targeted server. The program must be generic enough to work on blades (single iLO Dedicated NIC), rack-mount servers (Dedicated and Shared NICs), Moonshot servers (primary and secondary NICs)…

We are not using the previous BIOS/AdminName example because this network problem is a bit more complex, hence more interesting.

Following the methodology presented in the previous section, we need first to find a keyword in an iLO GUI or in the UEFI/BIOS menus that will help us to identify the Resource Type of iLO network interfaces.

Since the properties we want to list are related to iLOs, we can eliminate searching the UEFI/BIOS menus and focus only on the iLO GUI.

In this GUI, Network information can be found in two places of the left pane: Information -> System Information -> Network and Network. Keywords like Ethernet, NIC, and Adapter are mentioned several times in those screens and could be used to find the Resource Type we are looking for.

However, servers have as well a network subsystem used by the Operating System and those keywords could lead to the wrong Resource Type; searching for adapter in the Data Model Reference Guide returns the BaseNetworkAdapter Resource Type under the /rest/v1/Systems URI.

The problem is that the /rest/v1/Systems entry point URI contains only the properties of the compute node(s) in the server.

Fixed Entry Point URIs are depicted in the Managing HPE Servers using the RESTful API document and we learn from there that Management Processors properties and attributes are under the /rest/v1/Managers fixed entry point URI:

Hence, we need to find a Resource Type under /rest/v1/Managers.

Looking for keyword Ethernet in the Data Model Reference Guide returns the EthernetInterface Resource Type under the /rest/v1/Managers entry point URI:

Clicking on the EthernetInterface link leads to the corresponding paragraph describing all the properties of this Type. With a quick look at those properties (i.e. Hostname, IPv4Addresses…) we know we have found the right Resource Type:

The above screenshot tells us that our program will have to identify all the Managers {item}s under the /rest/v1/Managers entry point URI.

Then, for each of those items (aka resource instances), it will have to find all the EthernetInterfaces {item}s before retrieving their properties and attributes.

Great. But how do I get the list of all the Managers (iLOs) in a system? The answer starts with finding the Resource Type of Managers. Looking for keyword Managers the Data Model Reference Guide leads to:

By starting to crawl the Redfish model starting at the /rest/v1/Managers entry point URI to locate all the iLOs and then, for each iLO searching the EternetInterface Resource Type, our program will be valid for all kinds of servers.

Python implementation

While we illustrate this paragraph with an example of the python-ilorest-library, all the Redfish examples in both GitHub and the PowerShell gallery have the same structure, based upon Resource Types.

The python-ilorest-library contains an examples/Redfish directory with more than 50 examples as well as the redfishobject.py file containing functions and various other objects used by the examples.

Fortunately enough, example 20 of the library implements a solution to our problem. To be precise, this example retrieves only the properties of iLO NICs with a specific state (Active or Inactive); let’s study first the overall layout:

1. Import of the required python modules:
   
2. Definition of the desired function:
   
3. Main section:
   a. Creation of a RedfishObject initializing an authenticated and secure connection with the Redfish target:
   
   b. Call of the function defined above:
   

Take now a close look at the definition of the function; line 22, the first action is a search of all the instances (aka {item}s) of Resource Type Manager. and stores their path in variable instances. The trailing “.” of the Resource Type is a shortcut to the default version number:

The last part of the program parses each NIC (aka member of the response variable) and prints the properties depending on their state and on the Active/Inactive parameter:

Writing a Redfish program with this structure is the best way to have a long term validity code because as explained in this article.

Conclusion

Using the HPE Data Model Reference Guide for iLO (or its Markdown/Slate version) and the Managing Hewlett Packard Enterprise Servers with the RESTful API documents we could validate and implement with different tools a simple methodology for getting or setting Redfish properties from/into HPE servers. Although not tested by the author, this methodology should be valid in a heterogeneous datacenter containing various brands of server, providing they implement the Redfish standard.