node

Razor’s node slice is used in two ways within Razor. First, the node slice provides an interface that can be used view information about the nodes that are currently in the system, either in the form of a summary of the current nodes in the system (including their status, last checkin time, and any tags that have been applied to them) or in the form of a detailed set of information about a given node (including information that was gathered from that node using a Razor Microkernel instance). Second, the node slice provides the interface that is used by the Razor Microkernel instances themselves to checkin with Razor (periodically) and to register with Razor; a process that can be triggered by the Microkernel instances themselves (when they detect that the underlying facts that they are reporting to Razor about the node they have been deployed to have changed) or in response to a command from Razor (included as part of the response from Razor to a 'node checkin' request) instructing them to (re)register with the Razor server.

It should be noted here that there is no ability to update a node (or remove a node) provided as part of the node slice (in either the node slice’s CLI or the node slice’s RESTful API). Nodes are created during the initial node checkin/registration process and updated periodically by their Microkernel instances using that same process. Nodes are only removed from the system after they have been inactive for a specified period of time (the 'node_expire_timeout', which defaults to 300 seconds, or 5 minutes, in the current version of Razor). If a node remains inactive (i.e. does not checkin with Razor) for a period of time that exceeds this this 'node_expire_timeout' period it will be removed from the system by Razor (and forced to re-register as a new node instance if it checks in again in the future).

The node CLI

The node CLI provides a set of 'view-only' commands, that give the users the ability to 'get' information about a node (or set of nodes) from Razor:

razor node [get] [all]                      Display list of nodes
razor node [get] (UUID)                     Display details for a node
razor node [get] (UUID) [--field,-f FIELD]  Display node's field values

As you can see, there are options provided to get a summary view of all of the nodes currently registered with Razor (and their status) and to get a detailed view of a specific node (by UUID). Razor also provides users with the ability to display a list of all of the attributes that have been gathered from a specific node (and reported to Razor as part of the node registration process) using the 'razor node (UUID) --field attributes' command or to view a list of the hardware ID values that were reported to Razor by the node’s Microkernel during the node checkin/registration process using the 'razor node (UUID) --field hardware_ids' command. As is the case with many of the Razor CLI commands, aliases for these two field names are supported ('attrib' instead of 'attributes' and 'hardware' or 'hardware_id' instead of 'hardware_ids').

The node RESTful API

The node RESTful API is provided via two resources ('/node' and '/node/{UUID}'). There are two additional resources defined in the RESTful API ('/node/checkin' and '/node/register') that are used by the Razor Microkernel instances themselves; the first to periodically 'checkin' with Razor and the second to register (new) facts about their underlying nodes with Razor. The operations supported by these resources are as follows:

• GET /node -- used to get a summary view of all of the nodes that are registered with the system
• GET /node/{UUID} -- used to get the details of a specific node (by UUID); the details returned are the same as those returned in the previous operation, but the values returned are only those for that specific node instance.
• GET /node/{UUID}?field=attributes -- used to obtain a list of the latest set of attributes (facts) that were reported for the specified node by the Microkernel instance that was deployed to that node (as part of the node discovery process).
• GET /node/{UUID}?field=hardware_ids -- used to obtain a list of the hardware ID values that were reported for the specified node by the Microkernel instance that was deployed to that node (as part of the node discovery process). Razor uses these hardware ID values to identify the system in question (mapping that set of hardware ID values to a UUID value for a specific node within Razor).
• POST /node/checkin?[checkin_param_list] -- used by the Razor Microkernel instances to checkin periodically with the Razor server. The [checkin_param_list] value shown above is a simple list of name/value pairs that includes the hardware ID values for the node checking in, the 'last state' for that node (typically this is the string value 'idle'), and (optionally) a boolean value indicating whether or not this checkin is the first checkin by this node since it booted (or since it was rebooted). Once the node has checked in successfully with the Razor server, this last value can be left out of the request. An example of the use of this request by a Microkernel instance might be something like the following:

POST /node/checkin?hw_id=000C29291C95&last_state=idle&first_checkin=true

Note; the hw_id value is currently set to an underscore-separate list of the stripped MAC address values for the NICs in a node (something like '000C29291C95_000C29291C96' for a node with two NICs that have MAC addresses of 00:0C:29:29:1C:95 and 00:0C:29:29:1C:96). This use of the combined list of MAC addresses of a node’s NICs as a unique identifier for a given node might be changed in the future, but for now that how the the hardware ID value is constructed (and how a node is uniquely identified by Razor).

• POST /node/{UUID}?[registration_param_list] -- used to (re)register a node with Razor. As was the case with the checkin request (above), a list of parameters (the [registration_param_list]) must be included as part of this request. The parameters in that list must include the hardware ID list for the node, the node’s last state, and a hash map containing the facts gathered for that node by the Microkernel. An example of this request might look something like the following:

POST /node/register?hw_id=000C29291C95&last_state=idle&attributes_hash={JSON_HASH}

Note; in this example we have not shown the actual attributes_hash value (for brevity), just the string {JSON_HASH} where that value would appear. The value included as part of an actual node registration request would be a JSON-encoded Hash map containing the current facts (attributes) being registered with Razor for the node with the stated hardware ID value. Note that it is these attributes (reported during the node registration process) that are used within the tag matchers defined for the tags in the system to determine what tags should be applied to a given node.