Forming node classifier API requests

Requests to the node classifier API must be well-formed HTTP(S) requests.

By default, the node classifier service listens on port 4433 and all endpoints are relative to the /classifier-api/ path. For example, the full URL for the /v1/groups endpoint on localhost would be https://localhost:4433/classifier-api/v1/groups.

If needed, you can change the port the classifier API listens on.

Node classifier API requests must include a URI path following the pattern:

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

The variable path components derive from:

• DNS: Your PE console host's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
• VERSION: Either v1 or v2. Refer to Node classifier API v2 for v2 endpoints.
• ENDPOINT: One or more sections specifying the endpoint, such as groups or classes. Some endpoints require additional sections, such as the GET /v1/environments/<environment>/classes endpoint.

For example, you could use any of these paths to call the GET /v1/classes endpoint:

https://$(puppet config print server):4433/classifier-api/v1/classes
https://localhost:4433/classifier-api/v1/classes
https://puppet.example.dns:4433/classifier-api/v1/classes

To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply the content type and/or additional parameters specific to the endpoint you are calling.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Rule condition grammar

You can use rules to dynamically classify nodes into groups. When forming requests to endpoints that support rule definition, you must use proper rule condition grammar, such as:

    condition  : [ {bool} {condition}+ ] | [ "not" {condition} ] | {operation}
         bool  : "and" | "or"
    operation  : [ {operator} {fact-path} {value} ]
     operator  : "=" | "~" | ">" | ">=" | "<" | "<=" | "<:"
    fact-path  : {field-name} | [ {path-type} {field-name} {path-component}+ ]
    path-type  : "trusted" | "fact"
path-component : field-name | number
    field-name : string

For the regex operator "~", the value is interpreted as a Java regular expression. You must use literal backslashes to escape regex characters in order to match those characters in the fact value.

For the numeric comparison operators (">", ">=", "<", and "<="), the fact value (which is always a string) is coerced to a number (either integral or floating-point). If the value can't be coerced to a number, the numeric operation evaluates to false.

For the array contains operator "<:", the fact value must be an array.

For the fact-path, the rule can be either a string representing a top level field (such as name, representing the node name) or a list of strings and indices that represent looking up a field in a nested data structure. When passing a list of strings or indices, the first and second entries in the list must be strings and subsequent entries can be indices.

Regular facts start with "fact" (for example, ["fact", "architecture"]) and trusted facts start with "trusted" (for example, ["trusted", "certname"]).

Related information

• Configure the console