Nodes check-in history endpoints

Use the nodes endpoints to retrieve records about nodes that have checked into the node classifier.

Enable check-in storage to use this endpoint

By default, node check-in storage is disabled because it can place excessive loads on larger deployments. You must enable node check-in storage to get any information from the nodes endpoints. If node check-in storage is disabled, the nodes endpoints return empty arrays.

To enable node check-in storage, set the classifier_node_check_in_storage parameter in the puppet_enterprise::profile::console class to true.

GET /v1/nodes

Retrieve check-in history for all nodes that have checked in with the node classifier.

Request format

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication. For example:
GET https://localhost:4433/classifier-api/v1/nodes
You can append these optional parameters to the URI path:
  • limit: Set the maximum number of nodes to include in the response. For example, limit=10 limits the response to 10 nodes. The point at which the limit count starts is determined by offset.
    Tip: The amount of time it takes the endpoint to respond depends on the number of records it has to collect. In deployments that have a very large amount of nodes, the console-services process might run out of memory and crash. If your deployment has a lot of nodes, setting the limit parameter can expedite the response time and avoid crashes.
  • offset: Specify a zero-indexed integer at which to start returning results. For example, if you set this to 12, the response returns nodes starting with the 13th record. The default is 0.
For example, this request includes the limit and offset parameters:
GET https://localhost:4433/classifier-api/v1/nodes?limit=25&offset=25

Response format

A successful response returns a JSON array of objects. Each object contains:
  • name: The name of the node, as a string.
  • check_ins: An array of objects where each object represents a node classifier check-in event.
Each check-in object uses these keys:
  • time: The check-in time, as a string in ISO-8601 format with timezone.
  • explanation: An object containing IDs of node groups the node was classified into (during the check-in event) and sub-objects explaining which rule(s) the node matched to be classified into the group. Rule explanation objects use these keys:
    • value: A Boolean indicating the result of evaluating the form. At the top level, this is the result of the entire rule condition. Within complex rules, you can use the value to trace individual rule condition results, For example, you can check which parts of an or condition were true.
    • form: A representation of a rule condition. Additional conditions within a complex rule are represented as nested rule explanation objects.
    Tip: If you want more detailed classification explanations, use the POST /v1/classified/nodes/<name>/explanation endpoint.
  • transaction_uuid: A UUID representing a specific Puppet transaction that is submitted by Puppet at the time of the check-in event. This makes it possible to identify the check-in event that generated a specific catalog and report.

Besides the rule condition markup, the comparison operations in the rule conditions have their first argument (the fact path) replaced with an object that has both the fact path and the value that was found in the node at that path.

Here is an example of a response object for one node:
{
  "name": "Deep Space 9",
  "check_ins": [
    {
      "time": "2369-01-04T03:00:00Z",
      "explanation": {
        "53029cf7-2070-4539-87f5-9fc754a0f041": {
          "value": true,
          "form": [
            "and",
            {
              "value": true,
              "form": [">=", {"path": ["fact", "pressure hulls"], "value": "3"}, "1"]
            },
            {
              "value": true,
              "form": ["=", {"path": ["fact", "warp cores"], "value": "0"}, "0"]
            },
            {
              "value": true,
              "form": [">" {"path": ["fact", "docking ports"], "value": "18"}, "9"]
            }
          ]
        }
      }
    }
  ],
  "transaction_uuid": "d3653a4a-4ebe-426e-a04d-dbebec00e97f"
}
To help explain the response, assume a node named Deep Space 9 checked into the classifier, and, at check-in time, the node had these facts:
"fact": {
    "pressure hulls": "10",
    "docking ports": "18",
    "docking pylons": "3",
    "warp cores": "0",
    "bars": "1"
  }
Also assume this rule existed for a node group:
["and", [">=", ["fact", "pressure hulls"], "1"],
        ["=", ["fact", "warp cores"], "0"],
        [">=", ["fact", "docking ports"], "10"]]
Tip: Refer to Forming node classifier API requests for an explanation of rule condition grammar.
When the Deep Space 9 node checks in for classification, the node's facts caused it to match the rule. When you check the check-in history, the rule explanation object demonstrates the logic behind the rule evaluation that ultimately classified the node into that particular node group. For example:
{
  "value": true,
  "form": [
    "and",
    {
      "value": true,
      "form": [">=", {"path": ["fact", "pressure hulls"], "value": "3"}, "1"]
    },
    {
      "value": true,
      "form": ["=", {"path": ["fact", "warp cores"], "value": "0"}, "0"]
    },
    {
      "value": true,
      "form": [">" {"path": ["fact", "docking ports"], "value": "18"}, "9"]
    }
  ]
}

Error responses

Possible errors follow the usual format for Node classifier API errors.

GET /v1/nodes/<node>

Retrieve the check-in history for a specific node.

Request format

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication. The URI path must specify a node name. For example:
GET https://localhost:4433/classifier-api/v1/nodes/Node1234

Response format

The response is the same as the GET /v1/nodes endpoint response, but the response only contains information for the specified node.

Error responses

If there is no check-in information for the node with the given name, the endpoint returns a 404 Not Found response. Other possible errors follow the usual format for Node classifier API errors.