6.7. Nodes and Catalogs

Nodes are the elements that RackHD manages - compute servers, switches, etc. Nodes typically have at least one catalog, and can have Pollers and Workflow Graphs assigned to or working against that node.

Catalogs are free form data structures with information about the nodes. Catalogs are created during ‘discovery’ workflows, and present information that can be requested via API and is available to workflows to operate against.

6.7.1. Defining Nodes

Nodes are defined via a JSON definition that conform to this schema:

  • id (string): unique identifier for the node
  • type (string): a human readable name for the graph
  • name (string): a unique name used by the system and the API to refer to the graph
  • autodiscover (boolean):
  • sku (string): the SKU ‘id’ that has been matched from the SKU workflow task
  • createdAt (string): ISO8601 date string of time resource was created
  • updatedAt (string): ISO8601 date string of time resource was last updated
  • identifiers (array of strings): a list of strings that make up alternative identifiers for the node
  • obms (array of objects): a list of objects that define out-of-band management access mechanisms
  • relations (array of objects): a list of relationship objects

6.7.2. Defining Catalogs

  • id (string): unique identifier for the node
  • createdAt (string): ISO8601 date string of time resource was created
  • updatedAt (string): ISO8601 date string of time resource was last updated
  • data (json): A JSON data structure specific to the catalog tool
  • node (string): the node to which this catalog is associated
  • source (string): type of the data

6.7.3. API Commands for Nodes

The following are common API commands that can be used when running the on-http process.

Get Nodes

GET /api/current/nodes
curl <server>/api/current/nodes

Get Specific Node

GET /api/current/nodes/<id>
curl <server>/api/current/nodes/<id>

Sample switch node after Discovery

{
    "type":"switch",
    "name":"nodeName",
    "autoDiscover":true,
    "service": "snmp-ibm-service",
    "config": {
        "host": "10.1.1.3"
    },
    "createdAt":"2015-07-27T22:03:45.353Z",
    "updatedAt":"2015-07-27T22:03:45.353Z",
    "id":"55b6aac1024fd1b349afc145"
}

Sample compute node after Discovery

{
    "autoDiscover": false,
    "catalogs": [],
    "createdAt": "2015-11-30T21:37:18.441Z",
    "id": "565cc18ec3f522fe51620fa2",
    "identifiers": [
        "08:00:27:27:eb:12"
    ],
    "name": "08:00:27:27:eb:12",
    "obms": [
        {
            "ref": "/api/2.0/obms/58806bb776fab9d82b831e52",
            "service": "noop-obm-service"
        }
    ],
    "relations": [
        {
            "relationType": "enclosedBy",
            "targets": [
                "565cc1d2807f92fc51a7c9c5"
            ]
        }
    ],
    "sku": "565cb91669aa70ab450da9dd",
    "type": "compute",
    "updatedAt": "2015-11-30T21:38:26.755Z",
    "workflows": []
}

List all the (latest) catalog data associated with a node

GET /api/current/nodes/<id>/catalogs
curl <server>/api/current/nodes<id>/catalogs

To retrieve a specific catalog source for a node

GET /api/current/nodes/<id>/catalogs/<source>
curl <server>/api/current/nodes<id>/catalogs/<source>

Sample Output:

{
    "createdAt": "2015-11-30T21:37:49.696Z",
    "data": {
        "BIOS Information": {
            "Address": "0xE0000",
            "Characteristics": [
                "ISA is supported",
                "PCI is supported",
                "Boot from CD is supported",
                "Selectable boot is supported",
                "8042 keyboard services are supported (int 9h)",
                "CGA/mono video services are supported (int 10h)",
                "ACPI is supported"
            ],
            "ROM Size": "128 kB",
            "Release Date": "12/01/2006",
            "Runtime Size": "128 kB",
            "Vendor": "innotek GmbH",
            "Version": "VirtualBox"
        },
        "Base Board Information": {
            "Asset Tag": "Not Specified",
            "Chassis Handle": "0x0003",
            "Contained Object Handles": "0",
            "Features": [
                "Board is a hosting board"
            ],
            "Location In Chassis": "Not Specified",
            "Manufacturer": "Oracle Corporation",
            "Product Name": "VirtualBox",
            "Serial Number": "0",
            "Type": "Motherboard",
            "Version": "1.2"
        },
        "Chassis Information": {
            "Asset Tag": "Not Specified",
            "Boot-up State": "Safe",
            "Lock": "Not Present",
            "Manufacturer": "Oracle Corporation",
            "Power Supply State": "Safe",
            "Security Status": "None",
            "Serial Number": "Not Specified",
            "Thermal State": "Safe",
            "Type": "Other",
            "Version": "Not Specified"
        },
        "Inactive": [
            {},
            {},
            {}
        ],
        "OEM Strings": {
            "String 1": "vboxVer_5.0.10",
            "String 2": "vboxRev_104061"
        },
        "OEM-specific Type": {
            "Header and Data": [
                "80 08 08 00 E7 7D 21 00"
            ]
        },
        "System Information": {
            "Family": "Virtual Machine",
            "Manufacturer": "innotek GmbH",
            "Product Name": "VirtualBox",
            "SKU Number": "Not Specified",
            "Serial Number": "0",
            "UUID": "992DA874-C028-4CDD-BB06-C86D525A7056",
            "Version": "1.2",
            "Wake-up Type": "Power Switch"
        }
    },
    "id": "565cc1ad807f92fc51a7c9bf",
    "node": "565cc18ec3f522fe51620fa2",
    "source": "dmi",
    "updatedAt": "2015-11-30T21:37:49.696Z"
}

6.7.4. Out of Band Management Settings

Get list of Out of Band Management settings that have been associated with nodes.

Get list of OBMs settings

GET /api/current/obms
curl <server>/api/current/obms

Get list of OBMs schemas showing required properties to create an OBM

GET /api/current/obms/definitions
curl <server>/api/current/obms/definitions

Create or update a single OBM service and associate it with a node

PUT /api/current/obms
curl -X PUT -H "Content-Type: application/json" -d '{ "nodeId": <node id>, "service": "ipmi-obm-service", "config": { "user": "admin", "password": "admin", "host": "<host ip>" } }' /api/current/obms

Example output of PUT

{
  "id": "5911fa6447f8b7b207f9a485",
  "node": "/api/2.0/nodes/590cbcbf29ba9e40471c9f3c",
  "service": "ipmi-obm-service",
  "config": {
    "user": "admin",
    "host": "172.31.128.2"
  }
}

Get a specific OBM setting

GET /api/current/obms/<id>
curl <server>/api/current/obms/<id>

PATCH an OBM setting

PATCH /api/current/obms/<id>
curl -X PUT -H "Content-Type: application/json" -d '{ "nodeId": <node id>, "service": "ipmi-obm-service", "config": { "user": "admin", "password": "admin", "host": "<host ip>" } }' /api/current/obms/<id>

Delete an OBM setting

DELETE /api/current/obms/<id>
curl -X DELETE <server>/api/current/obms/<id>

To set a no-op OBM setting on a node

curl -X PUT -H "Content-Type:application/json" localhost/api/current/nodes/5542b78c130198aa216da3ac -d '{  { "service": "noop-obm-service", "config": { } } }'

To set a IPMI OBM setting on a node

curl -X PUT -H 'Content-Type: application/json' -d ' { "service": "ipmi-obm-service", "config": { "host": "<host ip>", "user": "admin", "password": "admin" } }' <server>/api/current/nodes/<nodeID>/obm

How to use obms when more than one obm are present on a node

Example: when update firmware workflow is called on a node that has multiple obms (ipmi-obm-service, redfish-obm-service), the payload needs to call out what obm service to use for certain tasks within the workflow that use the obm service..

POST /api/current/nodes/<id>/nodes/workflows?name=Graph.Dell.Racadm.Update.Firmware
{
  "options": {
          "defaults": {
                        "filePath": "xyz",
                        "serverUsername": "abc",
                        "serverPassword": "123",
                        "serverFilePath": "def"
           },
   "set-boot-pxe": {
                        "obmServiceName": "ipmi-obm-service"
                        },
   "reboot": {
                        "obmServiceName": "ipmi-obm-service"
   }
 }

6.7.5. In Band Management Settings

Get list of In Band Management settings that have been associated with nodes.

Get list of IBMs settings

GET /api/current/ibms
curl <server>/api/current/ibms

Get list of IBMs schemas showing required properties to create an IBM

GET /api/current/ibms/definitions
curl <server>/api/current/ibms/definitions

Create or update a single IBM service and associate it with a node

PUT /api/current/ibms
curl -X PUT -H "Content-Type: application/json" -d '{ "nodeId": <node id>, "service": "snmp-ibm-service", "config": { "community": "public", "host": "<host ip>" } }' /api/current/ibms

Example output of PUT

{
  "id": "591c569c087752c67428e4b3",
  "node": "/api/2.0/nodes/590cbcbf29ba9e40471c9f3c",
  "service": "snmp-ibm-service",
  "config": {
    "host": "172.31.128.2"
  }
}

Get a specific IBM setting

GET /api/current/ibms/<id>
curl <server>/api/current/ibms/<id>

PATCH an IBM setting

PATCH /api/current/ibms/<id>
curl -X PUT -H "Content-Type: application/json" -d '{ "nodeId": <node id>, "service": "snmp-ibm-service", "config": { "community": "public", "host": "<host ip>" } }' /api/current/ibms/<id>

Delete an IBM setting

DELETE /api/current/ibms/<id>
curl -X DELETE <server>/api/current/ibms/<id>

6.7.6. Node Tags

Add a tag to a node

PATCH /api/current/nodes/<id>/tags
curl -H "Content-Type: application/json" -X PATCH -d '{ "tags": [<list of tags>]}' <server>/api/current/nodes/<id>/tags

List tags for a node

GET /api/current/nodes/<id>/tags
curl <server>/api/current/nodes/<id>/tags

Delete a tag from a node

DELETE /api/current/nodes/<id>/tags/<tagname>
curl -X DELETE <server>/api/current/nodes/<id>/tags/<tagname>

6.7.7. Node Relations

List relations for a node

GET <server>/api/current/nodes/<id>/relations
curl <server>/api/current/nodes/<id>/relations

Sample response:

[
  {
      "relationType": "contains",
      "targets": [
            "57c0d980851053795fdc7bcf",
            "57c0d6bd851053795fdc7bc4"
          ]
    }
]

Add relations to a node

PUT <server>/api/current/nodes/<id>/relations
curl -H "Content-Type: application/json" -X PUT -d '{ <relationType>: [<list of targets>]}' <server>/api/2.0/nodes/<id>/relations

Sample request body:

{
    "contains":  ["57c0d980851053795fdc7bcf", "57c0d6bd851053795fdc7bc4"]
}

Sample response body:

[
  {
      "autoDiscover": false,
      "createdAt": "2016-08-30T18:39:57.819Z",
      "name": "demoRack",
      "relations": [
            {
                "relationType": "contains",
                "targets": [
                    "57c0d980851053795fdc7bcf",
                    "57c0d6bd851053795fdc7bc4"
                ]
            }
          ],
      "tags": [],
      "type": "rack",
      "updatedAt": "2016-08-30T21:07:11.717Z",
      "id": "57c5d2fd64bda4e679146530"
    },
  {
      "autoDiscover": false,
      "createdAt": "2016-08-27T00:06:24.784Z",
      "identifiers": [
            "08:00:27:10:1f:25"
          ],
      "name": "08:00:27:10:1f:25",
      "relations": [
            {
                "relationType": "containedBy",
                "targets": [
                    "57c5d2fd64bda4e679146530"
                ]
            }
          ],
      "sku": null,
      "tags": [],
      "type": "compute",
      "updatedAt": "2016-08-30T21:07:11.729Z",
      "id": "57c0d980851053795fdc7bcf"
    },
  {
      "autoDiscover": false,
      "createdAt": "2016-08-26T23:54:37.249Z",
      "identifiers": [
            "08:00:27:44:97:79"
          ],
      "name": "08:00:27:44:97:79",
      "relations": [
            {
                "relationType": "containedBy",
                "targets": [
                    "57c5d2fd64bda4e679146530"
                ]
            }
          ],
      "sku": null,
      "tags": [],
      "type": "compute",
      "updatedAt": "2016-08-30T21:07:11.724Z",
      "id": "57c0d6bd851053795fdc7bc4"
    }
]

Remove Relations from a node

DELETE <server>/api/current/nodes/<id>/relations
curl -H "Content-Type: application/json" -X DELETE -d '{ <relationType>: [<list of targets>]}' <server>/api/current/nodes/<id>/relations

Sample request body:

{
    "contains":  ["57c0d980851053795fdc7bcf", "57c0d6bd851053795fdc7bc4"]
}

Sample response body:

[
  {
      "autoDiscover": false,
      "createdAt": "2016-08-30T18:39:57.819Z",
      "name": "demoRack",
      "relations": [],
      "tags": [],
      "type": "rack",
      "updatedAt": "2016-08-30T21:14:11.553Z",
      "id": "57c5d2fd64bda4e679146530"
    },
  {
      "autoDiscover": false,
      "createdAt": "2016-08-27T00:06:24.784Z",
      "identifiers": [
            "08:00:27:10:1f:25"
          ],
      "name": "08:00:27:10:1f:25",
      "relations": [],
      "sku": null,
      "tags": [],
      "type": "compute",
      "updatedAt": "2016-08-30T21:14:11.566Z",
      "id": "57c0d980851053795fdc7bcf"
    },
  {
      "autoDiscover": false,
      "createdAt": "2016-08-26T23:54:37.249Z",
      "identifiers": [
            "08:00:27:44:97:79"
          ],
      "name": "08:00:27:44:97:79",
      "relations": [],
      "sku": null,
      "tags": [],
      "type": "compute",
      "updatedAt": "2016-08-30T21:14:11.559Z",
      "id": "57c0d6bd851053795fdc7bc4"
    }
]