Node Classifier API v2

Introduction

Hey there! 

After being introduced to Puppet, have you wondered about how classifier data can be obtained for statically pinned or dynamically grouped nodes? Well, the answer is by using the Node Classifier API. 

Requests to the node classifier API must be HTTP(S) requests with all endpoints relative to the /classifier-api/ path. The API service usually listens on port 4433, which can be modified. Let us see the classification endpoints for the node classifier API v2.

Classification Endpoints

The API's classification endpoints accept a node name and a set of facts to return information on how the node is classified. This result can help test the node group classification rules. POST /v2/classified/nodes/<name> is the classification endpoint if the node classifier API.

Request Format

In general, the API requests' URI paths must follow the below pattern:

https://<DNS>:4433/classifier-api/<VERSION>/<ENDPOINT>

• DNS refers to the PE console host's DNS name.
• VERSION: v1 or v2
   

The URI path of v2 must contain the name of a specific node, and the body can contain a JSON object using the fact and trust keys. The fact key contains regular, non-trusted facts associated with the node as key-value pairs. The trusted key contains trusted facts associated with the node, also as key-value pairs. Fact values can be of any type.

Here is an example of the endpoint:

type='Content-Type: application/json'
auth="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v2/classified/nodes/<NAME>"
data='{"fact" : { "<NAME>" : "<VALUE>" }}'

curl --insecure --header "$type" --header "$auth" --request POST "$uri" --data "$data"

Response Format 

Successful API responses contain four keys to describe the node's classification - groups, environment, classes and parameters.

• Groups: It contains an array of the groups that the node was classified into. Each object represents a group. They are sorted by name.
   
• Environment: the environment used by the node.
   
• Classes: It contains an array of the names of the classes that the node received from the groups.
   
• Parameters: An object containing key-value pairs that describe the class parameter values for the node's classes.
   

{
  "groups": [{"id": "XXXXXXXXXXXXXXXXXXXXXX",
              "name": "groupA"},
            {"id": "XXXXXXXXXXXXXXXXXXXXXX",
              "name": "groupB"}],
  "environment": "dev",
  "classes": [" "],
  "parameters": {
    "apache": {
      "keepalive_timeout": 50     
    }
  }
}

Error Responses

Error responses have three keys - kind, msg and details. 

• The Node classifier API stores all error information within the kind key. 
   
• msg describes the reason for the conflict.
   
• The details key indicates the type of conflict.
   

The server returns a 500 Server error response if the node is classified into multiple node groups with conflicting classifications. The following detail objects are used to describe specific conflicts.

• value: It specifies the value with a conflict.
   
• from: The node group that caused the conflicting value to be added to the node's classification.
   
• defined_by: The node group that defined the conflicting value.