Validation endpoint

Use the validation endpoint to validate groups in the node classifier.

POST /v1/validate/group

Validate groups in the node classifier.

Request format

When Forming node classifier API requests to this endpoint, the body must be a JSON object describing the node group to be validated. The request uses these keys (which are required unless otherwise noted):
Key Definition
name

The name of the node group, as a string.
environment

The name of the node group's environment. This is optional. If omitted, the default value is production.
environment_trumps

When a node belongs to two or more groups, this Boolean indicates whether this node group's environment overrides environments defined by other node groups. This is optional. If omitted, the default value is false.
description

A string describing the node group. This is optional. If omitted, the node group has no description.
parent

The ID of the node group's parent. This is required.
rule

The condition that must be satisfied for a node to be classified into this node group.

For rule formatting assistance, refer to Forming node classifier API requests.
variables

An optional object that defines the names and values of any top-level variables set by the node group. Supply key-value pairs of variable names and corresponding variable values. Variable values can be any type of JSON value. The variables object can be omitted if the node group does not define any top-level variables.
classes

A required object that defines the classes to be used by nodes in the node group. The classes object contains the parameters for each class. Some classes have required parameters. This object contains nested objects – The classes object's keys are class names (as strings), and each key's value is an object that defines class parameter names and their values. Within the nested objects, the keys are the parameter names (as strings), and each value is the parameter's assigned value (which can be any type of JSON value). If no classes are declared, then classes must be supplied as an empty object ({}). If missing, the server returns a 400 Bad request response.
For example, this request validates a group called My Nodes:
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/validate/group"
data='{ "name": "My Nodes",
        "parent": "00000000-0000-4000-8000-000000000000",
        "environment": "production",
        "classes": {}
      }'

curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key "$key" --request POST "$uri" --data "$data"

Response format

If the group is valid, the service returns a 200 OK response with the validated group's information in the body.

Error responses

If there is an error, Node classifier API errors provide error information in the kind key. There are several errors you might encounter with the /v1/validate/group endpoint:
Response code Message Description
400 Bad Request schema-violation Required keys are missing or the value of any supplied key does not match the required type.
400 Bad Request malformed-request The request's body could not be parsed as JSON.
422 Unprocessable Entity uniqueness-violation The request content violates uniqueness constraints. For example, each node group name must be unique within distinct environments. The error response describes the invalid field.
422 Unprocessable Entity missing-referents Classes or class parameters declared on the node group, or inherited by the node group from its parent, do not exist in the specified environment. The error response lists the missing classes or parameters. The details contains an array of objects, where each object uses these keys to describe a single missing referent:
  • kind: Either "missing-class" or "missing-parameter", depending on whether the entire class doesn't exist, or the parameter is missing from the class.
  • missing: The name of the missing class or class parameter.
  • environment: The environment that the class or parameter is missing from.
  • group: The name of the node group where the error was encountered. Due to inheritance, this might not be the group where the parameter is actually defined.
  • defined_by: The name of the node group that defines the class or parameter. This can be the same as group or a parent of group.
422 Unprocessable Entity missing-parent The specified parent node group does not exist.
422 Unprocessable Entity inheritance-cycle The request causes an inheritance cycle. The error response contains a description of the cycle, including a list of the node group names, where each node group is followed by its parent until the first node group is repeated.