Use Redfish to manage servers automatically

While discussions of the cloud dominate the modern IT landscape, nearly every system administrator can fondly remember racking and configuring physical servers. Hardware configuration has classically been fraught with error-prone manual steps. Attempts to script the physical provisioning process often involved parsing the output of commands that were hostile to text-based processing. Manufacturer tools to interact with a system's baseboard management controller (BMC) usually printed challenging output that didn't lend itself to automation.

The Redfish standard from DMTF aims to change that experience. Redfish enables operators to interact with systems through standard web services, like HTTP and REST APIs. This approach makes it substantially easier to interrogate and configure physical systems. Instead of parsing output from a tool that is likely to change between versions, administrators can write robust automation to interact with HTTP-based APIs in their language of choice.

This article introduces the basics of using Redfish. While Redfish brings standardization to many configuration parameters, vendor implementations still vary. This article walks you through a vendor-agnostic scenario using the Redfish Mockup Server so that you can understand the underlying concepts for interacting with a Redfish system.

[ Download 5 steps to automate your business. ]

Run the Redfish Mockup Server

You don't need physical hardware to begin experimenting with Redfish. The DMTF maintains a Redfish Mockup Server that you can run to gain experience with the Redfish API. While you should always confirm that your automation works against the physical machines you intend to manage, the mockup server provides a great way to get started with the concepts.

First, clone the Redfish repository and install the necessary dependencies. I install them in a virtual environment to avoid cluttering my system Python:

# Clone the repository
$ git clone https://github.com/DMTF/Redfish-Mockup-Server.git

# Create and activate a virtual environment
$ python3 -m venv venv
$ source venv/bin/activate

# Install dependencies
(venv) $ cd Redfish-Mockup-Server
(venv) $ python3 -m pip install -r requirements.txt 

Next, start the mockup server by running the redfishMockupServer.py application. The server starts and listens on 127.0.0.1:8000 by default:

(venv) $ python3 redfishMockupServer.py 
Redfish Mockup Server, version 1.2.2
Hostname: 127.0.0.1
Port: 8000
Mockup directory path specified: public-rackmount1
Response time: 0 seconds
Serving Mockup in absolute path: /home/acritelli/Desktop/ac/Desktop/enable_sysadmin/redfish/Redfish-Mockup-Server/public-rackmount1
Serving Redfish mockup on port: 8000
running Server...

Finally, confirm that the server is functional by sending an HTTP request to localhost:8000/redfish:

$ curl localhost:8000/redfish
{
    "v1": "/redfish/v1"
}$ 

Gather information

Redfish is a true REST API that implements Hypermedia as the Engine of Application State (HATEOAS). You can explore the API, beginning at the root  endpoint and following links to other resources. This is a powerful concept, as you do not need any prior knowledge of Redfish or its data model to explore the resources exposed by the API.

Start by querying the /redfish/v1/Systems endpoint to obtain information about the systems managed by this Redfish instance. Consult the introductory documentation for more information about the types of high-level resources exposed by Redfish. You can see that the Members list contains a link to a specific system with a system ID of 437XR1138R2:

$ curl -s localhost:8000/redfish/v1/Systems
{
    "@odata.id": "/redfish/v1/Systems",
    "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Systems/437XR1138R2"
        }
    ],
    "Members@odata.count": 1,
    "Name": "Computer System Collection"
}$ 

Next, follow the link for the system to obtain information about it. Below, I pass the output to jq to find information about the processors in the system:

$ curl -s localhost:8000/redfish/v1/Systems/437XR1138R2 | jq .Processors
{
  "@odata.id": "/redfish/v1/Systems/437XR1138R2/Processors"
}

You can follow the Processors link to obtain information about all of the processors in the system. Just like with the systems endpoint, the Members list provides a list of processors in this system:

$ curl -s localhost:8000/redfish/v1/Systems/437XR1138R2/Processors
{
    "@odata.id": "/redfish/v1/Systems/437XR1138R2/Processors",
    "@odata.type": "#ProcessorCollection.ProcessorCollection",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Systems/437XR1138R2/Processors/CPU1"
        },
        {
            "@odata.id": "/redfish/v1/Systems/437XR1138R2/Processors/CPU2"
        },
        {
            "@odata.id": "/redfish/v1/Systems/437XR1138R2/Processors/FPGA1"
        }
    ],
    "Members@odata.count": 3,
    "Name": "Processors Collection"
}$ 

Finally, you can follow the link to find information about CPU1. Below, I pass the output to jq to find information about the operating speed for this particular processor model:

$ curl -s localhost:8000/redfish/v1/Systems/437XR1138R2/Processors/CPU1 \
    | jq .OperatingSpeedRangeMHz
{
  "AllowableMax": 3700,
  "AllowableMin": 1200,
  "ControlMode": "Automatic",
  "DataSourceUri": "/redfish/v1/Chassis/1U/Controls/CPU1Freq",
  "SettingMax": 2400,
  "SettingMin": 2000
}

Interrogating a system and following links is a powerful way to collect information programmatically. Sysadmins often need to collect data about systems for asset tracking and capacity planning purposes. Redfish provides a simple interface to gather this information.

Modify data

Querying information about a system is a great way to get started with Redfish and it is a great candidate for automation in most environments. However, Redfish isn't a read-only API. You can also use Redfish to configure details about remote systems. Building on its use of standard web concepts, Redfish leverages HTTP methods such as PATCH, PUT, and POST to modify the settings of a remote system.

To demonstrate this, I will simulate the steps involved in relocating a physical server from one rack to another. First, obtain information about the physical location of the 1U chassis associated with this system:

$ curl -s localhost:8000/redfish/v1/Chassis/1U \
    | jq .Location.Placement
{
  "Rack": "WEB43",
  "RackOffset": 12,
  "RackOffsetUnits": "EIA_310",
  "Row": "North"
}

The current placement information shows this chassis in the WEB43 rack. Suppose this server was moved to the DB06 rack and and you must update its placement information. Send a PATCH request to modify the physical location of the host. The PATCH request contains a JSON payload with updated location information, as shown below:

# JSON Update payload
$ cat location_update.json
{
    "Location": {
        "Placement": {
            "Rack": "DB06",
            "RackOffset": 8,
            "RackOffsetUnits": "EIA_310",
            "Row": "North"
          }
    }
}

# Send the PATCH request
$ curl -s -X PATCH -d @./location_update.json \
    -H 'Content-Type: application/json' \
    localhost:8000/redfish/v1/Chassis/1U 

Finally, confirm that the update was successful by querying the placement information:

$ curl -s localhost:8000/redfish/v1/Chassis/1U \
    | jq .Location.Placement
{
  "Rack": "DB06",
  "RackOffset": 8,
  "RackOffsetUnits": "EIA_310",
  "Row": "North"
}

The initial configuration of physical systems is an error-prone activity in many environments. Automation may reduce some of these errors and configure systems consistently according to organizational best practices. Redfish enables you to enact this configuration through a standard, programmatic interface.

Perform actions

Many Redfish resources also expose actions you can execute against them. For example, you may need to reboot a system or attach an ISO to the virtual media console. Redfish exposes these types of one-time actions. Following the RESTful principle of HATEOAS, you can discover the actions available for Redfish resources and the permitted values for these tasks.

For example, the individual systems in the Redfish mockup server expose a system reset action, as seen below.

Start by querying the individual system (437XR1138R2) in the mockup server and review the Actions object:

$ curl -s localhost:8000/redfish/v1/Systems/437XR1138R2 \
    | jq .Actions
{
  "#ComputerSystem.Reset": {
    "ResetType@Redfish.AllowableValues": [
      "On",
      "ForceOff",
      "GracefulShutdown",
      "GracefulRestart",
      "ForceRestart",
      "Nmi",
      "ForceOn",
      "PushPowerButton"
    ],
    "target": "/redfish/v1/Systems/437XR1138R2/Actions/ComputerSystem.Reset"
  },
  "Oem": {
    "#Contoso.Reset": {
      "target": "/redfish/v1/Systems/437XR1138R2/Oem/Contoso/Actions/Contoso.Reset"
    }
  }
}

The Actions object defines various individual actions that can be executed against the system, including the target uniform resource identifier (URI), and allowed actions for each. Execute the action by sending a POST request with an appropriate value for the ResetType, as shown below: 

$ curl -v -X POST -H 'Content-Type: application/json' \
    localhost:8000/redfish/v1/Systems/437XR1138R2/Actions/ComputerSystem.Reset \
    -d '{"ResetType":"ForceRestart"}'

No action is actually taken since the current endpoint is a mock server. However, a real system would reboot. A variety of actions are available for different resources, depending on the implementation. Additionally, manufacturers may implement their own actions. Since Redfish is a true REST API, you can easily explore and review the actions available for your hardware.

[ Looking for more on system automation? Get started with The Automated Enterprise, a complimentary book from Red Hat. ]

Wrap up

Any sysadmin with experience configuring physical hardware has felt the frustration of parsing challenging output from vendor-specific command line interface (CLI) tools. This difficulty has frequently stood in the way of building robust automation for provisioning and managing physical systems. Redfish introduces a standard method to programmatically discover and interface with physical systems.

In this article, you set up the Redfish Mockup Server and learned how to query, configure, and execute actions against remote systems. The Redfish API is very powerful, and I encourage you to investigate the options available on your physical systems.