Search our Blogs
Showing results for 
Search instead for 
Do you mean 
 

Getting Started with the iLO 4 Redfish API - A primer for coders

dmtf-redfish-logo.png

 

With the introduction of iLO 4 2.00 on ProLiant Gen9 servers, HPE introduced our next generation programmatic interface for server management.  iLO has a rich history of remote management capabilities including IPMI, SNMP, and our XML scripting language, but the software world has transitioned to REST APIs and the need for a next-generation server management API became apparent to us.

 

Our best chance transitioning from older interfaces to the new REST API was to work toward a new standard, so with the support of other industry leaders, we created the Redfish group in the DMTF.  The fundamental features of the new API were quickly agreed upon, and the first release emerged in August 2015.  As always happens, the standards process did result in some changes between our original API and the final Redfish standard.  In September 2015, we released iLO 4 2.30 which converges on the Redfish standard while maintaining pre-Redfish compatibility.  See the technical white paper “Redfish Implementation on HP RESTful API for iLO 4” for details on the differences between what we released in 2.00 and the 2.30 Redfish-conformant release.  HPE is committed to the new Redfish standard, and we encourage software developers to adjust client code to conform to Redfish.  If you are just beginning to look at the Redfish API, you should make sure your client code is interacting with iLO using Redfish standards:

 

  • Read the Redfish specification. Make sure your assumptions about service URIs, including the starting URI, do not exceed the specification’s guarantees.

 

  • Include the HTTP header “OData-Version”: “4.0” in all HTTP requests.  Including this header causes iLO 4 2.30 or later to hide any properties that did not make it into the Redfish standard (see the above mentioned white paper for details), decreasing the chance of inadvertently designing a dependency on something that has been replaced by a Redfish property.

 

As customers and our internal HPE teams have learned how to use the API, we have some concepts and best practices that we want to share with you that may help you understand the API and the philosophy behind its design.

 

How does Redfish versioning work?

Redfish is designed to allow the data model to develop quickly, at the pace of the industry, while limiting protocol and specification changes to infrequent updates.  For this reason, the data model is discoverable rather than statically documented in the specification.  Each resource has a versioned type (“@odata.type”) identifying a schema that defines the meaning of the values in the resource.  Although there are official releases of Redfish materials, there is no concept of conforming to a specific release of the Redfish schema.  Any implementation may mix resource types and versions from any release of Redfish without any concept of a global data model version.  For instance, a Redfish service may use ComputerSystem.v1_0_2 and Chassis.v1_2_0 in the same data model even if these two schemas were released at different times.

 

Redfish URIs – Writing Durable Client Code

Another characteristic of the discoverable data model is that each resource contains links to other resources.  Instead of a published list of resource URIs in the specification, a client discovers the data model dynamically by following links from each resource to the next.  This enables the data model to support many different use cases (e.g. multi-node compute modules or redundant management processors).

 

Client code should treat a Redfish link URI (“@odata.id”) as opaque.  A client should not attempt to deconstruct URIs into a template pattern.  It is entirely within spec for a resource at “/redfish/v1/systems/1” to contain a relative link to “/arbitrary/stuff”.  Only specific top level URIs documented in the specification may be assumed, and some links may not be implemented.  Other URIs must be discovered dynamically by following “@odata.id” links in the data model.

 

For example, the HPE ProLiant DL360 server is represented with one compute node, which iLO 4 implements at “/redfish/v1/systems/1/” but there are implementations and demonstration mockups that use different URIs including system serial number (e.g. “/redfish/v1/systems/<serial-number>”).  If you assume too much about the URIs, you will discover that your client code is not portable across various implementations of Redfish.  The proper way to find the compute node is to iterate the systems collection and discover the URIs to the individual nodes.

 

Traversing the Resource Model

Because objects link together, there are some best practices you should be aware of as you create new client code.  If you create a generic “crawler” client that simply GETs every resource and follows its links, your crawl will never terminate because the various object interlinks mean that the data model is not strictly a tree, but a graph.  A generic crawler must keep track of visited URIs and not re-crawl them.  Additionally, as best practice you should treat the visited resource URIs set as case insensitive (iLO does).  Most use cases are not generic crawls so this won’t be an issue.  Typically you know what you want to find in the data model, and you should iterate the collections needed to get to the specific resource.

 

Other Bits of Advice

Here are a few other things to consider:

 

Make sure your client code can handle other HTTP status results like 30x redirect.  iLO 4 makes use of HTTP 308 as a way to redirect old URIs to replacement URIs.

 

Redfish is intended to be implemented on management processors embedded on every server and it is likely that you will encounter many with self-signed TLS certificates.  By default, client code will not connect successfully to a Redfish service unless you first install a trusted TLS certificate.

 

How interoperable is Redfish across implementations?  It’s still early in the new standard’s life, but we did discover that our internal tools at HPE required only minor tweaking to work correctly on another implementation of Redfish.  If you read the specification and understand the principles behind the design choices, you have a very good chance of writing durable client code that is widely interoperable.

 

Here at HPE, we are very excited about the adoption of a RESTful API to improve the server management experience. To learn more about iLO’s implementation, and continue to learn best practices, stay tuned for more blogs and visit our GitHub repository to get started.

Tags: iLO 4| Redfish
Social Media
† The opinions expressed above are the personal opinions of the authors, not of HPE. By using this site, you accept the Terms of Use and Rules of Participation