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:
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 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"]).

Node classifier API authentication

You must authenticate node classifier API requests. You can do this using RBAC authentication tokens or with the list of allowed RBAC certificates.

Authenticating with tokens

You can make requests to the node classifier API using RBAC authentication tokens.

For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.

This example uses a token generated with puppet-access login to call the GET /v1/groups endpoint:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups"

curl --insecure --header "$auth_header" "$uri"

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

The example above uses the X-Authentication header to supply the token information. In some cases, such as with GitHub webhooks, you might need to supply the token in a token parameter. For example:
uri="https://$(puppet config print server):4433/classifier-api/v1/groups?token=$(puppet-access show)"

curl --insecure "$uri"
CAUTION: Supplying the token as a token parameter is not as secure as using the X-Authentication method.

Authenticating with an allowed certificate

You can also authenticate requests using a certificate listed in RBAC's certificate allowlist. The RBAC allowlist is located at /etc/puppetlabs/console-services/rbac-certificate-allowlist. If you edit this file, you must reload the pe-console-services service for your changes to take effect by running: sudo service pe-console-services reload

To attach the certificate to a curl request, you must have the allowed certificate name and the private key to run the script. The certname in the request must match a certname in the allowlist file at /etc/puppetlabs/console-services/rbac-certificate-allowlist. For example:
type_header='Content-Type: application/json'
cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups"

curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key "$key" GET "$uri"

You do not need to use an agent certificate for authentication. You can use puppet cert generate to create a new certificate specifically for use with the API.

Using pagination parameters

If your installation has a large number of groups, classes, nodes, node check-ins, or environments, then node classifier API GET requests might return an excessively large results.

To limit the number of items returned, you can append the limit and offset parameters to your request URI paths:
  • limit: Set the maximum number of items allowed to be returned in the response. The value must be a non-negative integer.
  • offset: Specify the number of items to skip from the beginning of the possible results. The value must be a zero-indexed, non-negative integer. The response begins returning results from the point specified, for example if offset=10, the response skips the first 10 results and starts the response with the 11th record.
For example, if you specify an offset of 20 with a limit of 10 (as shown in the example below) the first 20 records are skipped, and the response returns records 21 through 30: 
type_header='Content-Type: application/json'
cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups?limit=10&amp;offset=20"

curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key $key "$uri"

Supplying non-integer values for these parameters returns a 400 Bad request response.

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