Node Objects

ICE ClusterWare™ node objects represent the computational nodes and other controllable entities inside the cluster (switches, PDUs, etc.).

When issuing requests, the UID field in the URL can be either the actual UID of the object, the name of the object as given in the "name" field, the MAC address, or the IP address. Thus, once a user, user1, has been created, it can be referenced through /admin/user1 or /admin/<UID>.

Data Fields

Node objects can have several fields:

name
      Assigned by ClusterWare; the name is computed from the naming pool pattern and
      the node’s index (which is also computed based on that pool’s membership)

description
      Optional: A text string with descriptive information

type
      Optional: Defaults to ‘compute’, can be one of ('unknown','compute','head',
                'simulated')

mac
      Required: Every node must have a MAC address

attributes
      Optional: A set of key-value pairs that are assigned to the node and may be used
                when configuring the node at boot-time

groups
      Optional: An ordered list of Attribute Groups that this node belongs to;
                attributes from each group will be applied (overwritten) based on the
                order of the groups

naming_pool
      Optional: A naming pool may be assigned and used to calculate the
                name, index, and IP address of the node

index
      Assigned by ClusterWare; the index (integer) is computed by ClusterWare based on
      the naming pool

ip
      Assigned by ClusterWare; the IP address is computed by ClusterWare based on the
      naming pool

power_uri
      Optional: The URI of the node’s BMC or IPMI controller; the power_uri can be a
                template with bracketed fields that are substituted with the node’s
                attribute, status, or hardware values (see examples below)

redfish_uri
      Optional

Additional Endpoints

Several endpoints provide finer-grained access to the list of Attribute Groups that the node belongs to. For example, POST /node/<UID>/groups allows appending one or more groups to the current list. To completely replace the list of groups, use the PATCH /node/<UID> action with the groups key.

GET /node/<UID>/groups
     Returns a list of Attribute Groups (UIDs) that the node belongs to

POST /node/<UID>/groups
     Accepts one key or a list of keys representing Attribute Groups that will be
     appended to the current list


DELETE /node/<UID>/groups
     Accepts one key or a list of keys representing Attribute Groups that will be
     removed from the current list of Attribute Groups

Several endpoints provide finer-grained access to the list of attributes assigned to this specific node. Issuing a POST /node/<UID>/attributes action will append one or more groups to the current list. To completely replace the attributes, use the PATCH /node/<UID> action with the attributes key. Note that nodes will inherit attributes from all groups that they belong to, and will then overwrite them with any node-specific attributes.

GET /node/<UID>/attributes
     Returns a JSON object for all of the attributes (key-value pairs) for this node;
     these may have assigned specifically to this node or may have been inherited from
     any of the Attribute Groups that it belongs to

PUT /node/<UID>/attributes
     Replaces the current set of node-specific attributes with the sent data; note
     that if a key is removed from the current set, it may still be inherited from a
     joined Attribute Group

PATCH /node/<UID>/attributes
     Updates the current set of node-specific attributes with the sent data; these
     values will take precedence over any joined Attribute Groups

DELETE /node/<UID>/attributes
     Accepts one key or a list of keys to be removed from the node-specific attributes;
     note that if an attribute is set by an Attribute Group, it will still be present
     in the node’s overall list of attributes (until it is removed from that Attribute
     Group or the node leaves that group)

Several endpoints are designed for power control functionality. The power_uri field is needed for deeper power control functions. For example, a power-off action will attempt to execute a graceful shutdown, but if that fails it will fallback to an IPMI or BMC power-off.

GET /node/<UID>/power_uri
     Returns a JSON object with “parsed” and “unparsed” keys; the “unparsed” key
     contains a single URI that can be used to connect to the power control unit; the
     “parsed” key contains an object with fields representing the server, path, etc.
     that have been parsed from the URI

GET /node/<UID>/power_state
     Returns the power state of the node:  on, off, unknown

PUT /node/<UID>/power_state
     Accepts an object with “state” and “force” fields (all optional); “state” is one
     of: power on, power off; “force” is True or False.  There is an advanced option,
     “steps”, which allows for more control over the sequence of power-control attempts
     (for example, hard versus soft power-off) – contact Penguin Solutions for more
     information.

Several endpoints are used for the node status and hardware reporting system. Note that this is separate from the ClusterWare Monitoring and Alerting system; this data is kept inside the ClusterWare database and can be used in various templates and node-selectors. The specific values to be found in status and hardware can be configured using a plugin system. More information on monitoring and the plugin system can be found in the ClusterWare Admin and Reference Guides.

GET /node/<UID>/status
     Returns a JSON object with the node’s status information – this can be a sizeable
     set of data (several KB); with default plugins, status will include things like
     load average (load_avg) and memory usage (ram_free) as well as a list of the
     loaded packages and modules and many more.

POST /node/putstatus
     Accepts a JSON object with a “uid” field (required) and “status” and/or “hardware”
     keys; the “status” or “hardware” keys are JSON objects containing the actual data.
     This endpoint is intended to be used by ClusterWare tools to update node status
     information.

POST /node/putattribs
     Accepts a JSON object with a “uid” field (required) and a set of key-value pairs;
     the key-value pairs will be added to the node’s current attributes. This endpoint
     is intended to be used by ClusterWare tools to update node attribute information.

Related to the above, the following two endpoints are used by the compute nodes to update information on the ClusterWare head nodes. These endpoints do not use token-based authentication, but instead look at the IP-address of the incoming connection to determine which node is being updated.

Caution

Improper use of these endpoints could corrupt the ClusterWare node information, which could lead to improper functioning of Dynamic Groups, node selectors, and the Publish-Subscribe system. Contact Penguin Solutions for more information.

PUT /node/putstatus
     Accepts a JSON object with “status” and/or “hardware” keys, each of which is a
     JSON object containing the actual data; unlike the POST version of this endpoint,
     there is no “uid” key needed with the PUT operation

PUT /node/putattribs
     Accepts a JSON object with key-value pairs; these key-value pairs will be added
     to the node’s attributes; unlike the POST version of this endpoint, there is no
     “uid” key needed with the PUT operation

To interact with the nodes, including running commands on them, several endpoints can be used:

PUT /node/<UID>/exec
     Accepts a JSON object with “cmd” (required) and an optional “stdin” key; if
     “stdin” is sent, it will be used as the standard input for an interactive command;
     the output will be an octet-stream with the output from the command.  Note that
     this output format is different from other ClusterWare commands – there are no
     “success” or “data” keys, just the raw data from the command.

Example

Create a new node:

curl -X POST https://head1.cluster.local/api/v1/nodes --data \
    '{"mac":"11:22:33:44:55:66"}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "341b9947f6e644b78f6d88f5d7f898f4"}

Verify the node’s data using the returned UID:

curl -X GET https://head1.cluster.local/api/v1/node/341b9947f6e644b78f6d88f5d7f898f4 \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"mac": "11:22:33:44:55:66", "attributes": \
    {"_boot_config": "DefaultBoot"}, "index": 3, "ip": "192.168.122.103", \
    "type": "compute", "last_modified": 1721997178.5100713, "last_modified_on": \
    "head23.cluster.local", "last_modified_by": "admin1",  "uid": \
    "341b9947f6e644b78f6d88f5d7f898f4", "groups": [], "hardware": {}, \
    "power_uri": null, "name": "n3", "hostname": "n3", "domain": "cluster.local"}}

Since Nodes can be referenced by name or MAC address, the same information can be found using:

curl -X GET https://head1.cluster.local/api/v1/node/11:22:33:44:55:66 -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

And now that the node name is known, the same information can be found with:

curl -X GET https://head1.cluster.local/api/v1/node/n3 -H "Authorization: Bearer \
    eyJhbGciOiJIUzI1Ni…"

Set attributes on the node itself (not through an Attribute Group):

curl -X PATCH https://head1.cluster.local/api/v1/node/n3/attributes --data \
    '{"ipmi_user":"service", "ipmi_pass":"servicepass"}' -H "Authorization: \
   Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}

Verify the new data, grabbing just the attributes (not the whole node record):

curl -X GET https://head1.cluster.local/api/v1/node/n3/attributes -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"_boot_config": "DefaultBoot","ipmi_user": "service", \
    "ipmi_pass": "servicepass"}}

Setting the power_uri using the attributes in the template

curl -X PATCH https://head1.cluster.local/api/v1/node/n3 --data \
    '{"power_uri":"ipmi://<ipmi_user>:<ipmi_pass>@10.10.1.3/ipmi"}' \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}

Verify the power_uri and its substitutions

curl -X GET https://head1.cluster.local/api/v1/node/n3/power_uri -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"unparsed": "ipmi://service:servicepass@10.10.1.3/ipmi", \
    "parsed": {"scheme": "ipmi", "schemes": "", "server": "10.10.1.3", "path": \
    "ipmi", "server_username": "service:servicepass", "username": null, \
    "password": null, "host": "ipmi"}}}

Notice that the text strings “<ipmi_user>” and “<ipmi_password>” have been substituted for the values from the node’s attributes. To get the un-substituted value for the power_uri, simply use the GET /node/<UID> endpoint.

To determine the power state of the node:

curl -X GET https://head1.cluster.local/api/v1/node/n3/power_state -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "on"}

Note that if the node is unreachable via its primary or management network, it may take a while for the system to determine that the node is down just due to standard network timeouts.

To power off the node:

curl -X PUT https://head1.cluster.local/api/v1/node/n3/power_state --data \
    '{"state":"power off"}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}