Puppet Enterprise 2017.3

Use the nodes endpoint to retrieve historical information about nodes that have checked into the node classifier.

GET /v1/nodes

Use the /v1/nodes endpoint to retrieve a list of all nodes that have checked in with the node classifier, each with their check-in history.

Note: This endpoint is deprecated and will be removed in a future version of PE. Node history for a specific node can be obtained using the /v1/nodes/\<node\> endpoint. To count the number of nodes in your infrastructure, use the API.**

Response format

The response is a JSON array of node objects. Each node object contains these two keys:

Key Definition
name The name of the node according to Puppet (a string).
check_ins An array of check-in objects (described below).

Each check-in object describes a single check-in of the node. The check-in objects have the following keys:

Key Definition
time The time of the check-in as a string in ISO 8601 format (with timezone).
explanation An object mapping between IDs of groups that the node was classified into and explained condition objects that describe why the node matched this group's rule.
transaction_uuid A uuid representing a particular Puppet transaction that is submitted by Puppet at classification time. This makes it possible to identify the check-in involved in generating a specific catalog and report.

The explained condition objects are the node group's rule condition marked up with the node's value and the result of evalaution. Each form in the rule (that is, each array in the JSON representation of the rule condition) is replaced with an object that has two keys:

Key Definition
value A boolean that is the result of evaluating this form. At the top level, this is the result of the entire rule condition, but since each sub-condition is marked up with its value, you can use this to understand, say, which parts of an or condition were true.
formThe condition form, with all sub-forms as further explained condition objects.

Besides the condition markup, the comparison operations of the rule condition will 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.

The following example shows the format of an explained condition.

Start with a node group with the following rule:

["and", [">=", ["fact", "pressure hulls"], "1"],
        ["=", ["fact", "warp cores"], "0"],
        [">=", ["fact", "docking ports"], "10"]]

The following node will check into the classifier:

{
  "name": "Deep Space 9",
  "fact": {
    "pressure hulls": "10",
    "docking ports": "18",
    "docking pylons": "3",
    "warp cores": "0",
    "bars": "1"
  }
}

When the node checks in for classification, it will match the above rule, so that check-in's explanation object will have an entry for the node group that the rule came from. The value of this entry will be this explained condition object:

{
  "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"]
    }
  ]
}

GET /v1/nodes/<node>

Use the /v1/nodes/\<node\> endpoint to retrieve the check-in history for only the specified node.

Response format

The response will be one node object as described above, for the specified node. The following example shows a node object:

{
  "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"
}

Error responses

If the specified node has not checked in, the service returns a 404: Not Found response, with the usual JSON error response in its body.

Back to top