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,
    "snmpSettings":{
        "host":"10.1.1.3",
        "community":"HZTvBPqhg4ccDop5mfyziw==.wIeqRE9y0s0/o5cDWa4OLw==",
        "nodeId":"55b6aac1024fd1b349afc145"
    },
    "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"
}

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": "10.1.1.3", "user": "admin", "password": "admin" } }' \
    {server}/api/current/nodes/{nodeID}/obm

6.7.4. 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.5. 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"
    }
]