POST /v1/groups

Create a node group with a randomly-generated ID.

Request format

When Forming node classifier API requests to this endpoint, the body must be a JSON object describing the node group to be created. 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.
`config_data`	An optional object that defines the class parameters to be used by nodes in the group. Its structure is the same as the `classes` object. No configuration data is stored if you supply a `config_data` object that only contains a class name, such as `"config_data": {"qux":{}}`. This feature is enabled by the `classifier::allow-config-data` setting. When set to `false`, supplying the `config_data` object triggers a 400 response.

For example, this request creates 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/groups"
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 node group was successfully created, the service returns a 303 See Other response with a URI path you can use with the GET /v1/groups/<id> endpoint to retrieve data for the new node group.

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 POST /v1/groups 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.