Group children endpoint

Use the group-children endpoint to retrieve a list of node groups descending from a specific node group.

GET /v1/group-children/<id>

Retrieve a list of node groups descending from a specific node group,

Request format

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. The ID must be a valid type-4 (random) UUID. You can use the GET /v1/groups endpoint to retrieve node group IDs.

You can append the optional depth parameter to limit how many levels of descendants are returned. For example, depth=2 limits the response to the group's immediate children and first grandchildren. For example:
GET https://localhost:4433/classifier-api/v1/group-children/085e2797-32f3-4920-9412-8e9decf4ef65?depth=2

depth must be an integer. If depth=0 the response only returns the base group and no children or grandchildren.

Response format

A successful response returns a JSON array of objects, where each object represents a node group. If grandchildren are present, the objects are nested to represent the node group ancestry tree.
Restriction: The response only contains information about node groups you have permission to view and the children of those node groups. If you specified a depth, the response is further constrained. Keep in mind that you might have permission to view a grandchild group but not that group's parent.
  • If you only have permission to view the specified group, the response contains the group's descendants.
  • If you have permission to view the descendants of the specified group, but not the specified group itself, the response returns children from each ancestry tree you have permission to view.
  • If you do not have permission to view either the specified group or its descendants, the response is an empty array.
Each node group object uses these keys:
Key Definition
name

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

The node group's ID, which is a string containing a type-4 (random) UUID. The regular expression used to validate node group UUIDs is [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}.
description

An optional key containing an arbitrary string describing the node group.
environment

The name of the node group's environment, as a string. This indirectly defines which classes are available to declare on the node group, and this is the environment that nodes in this node group run in.
environment_trumps

This is a Boolean that changes the response to conflicting environment classifications. By default, if a node belongs to multiple groups with different environments, a classification-conflict error is returned. If the environment_trumps flag is set on a node group, then that node group's environment overrides environments of other groups (if the other groups do not have this flag set), and no attempt is made to validate that the other node groups' classes and class parameters exist in this node group's environment. This is used, for example, with Environment-based testing.
parent

The ID of the node group's parent, as a string. The only node group without a parent is the All Nodes group, which is the root of the node group hierarchy. The root group, All Nodes, always has the lowest-possible random UUID, which is: 00000000-0000-4000-8000-000000000000
rule

A Boolean condition on node properties. When a node's properties satisfy this condition, it's classified into the node group.
classes

An object that defines both the classes consumed by nodes in this node group and any non-default values for their parameters. The keys of the object are the class names, and the values are objects describing the parameters. The parameter objects' keys are parameter names, and the values are what the node group sets for that parameter, which is always a string.
deleted

An object similar to the classes object that shows which classes and class parameters set by the node group have since been deleted. If none of the node group's classes or parameters have been deleted, this key is omitted. Checking for the presence of this key is an easy way to check whether the node group has references that need to be updated. The keys of this object are class names, and the values are also objects. These secondary objects always contain the puppetlabs.classifier/deleted key, whose value is a Boolean indicating whether the entire class has been deleted. The other keys of these objects are parameter names, and the other values are objects that always contain two keys: puppetlabs.classifier/deleted, which is a Boolean indicating whether the specific class parameter has been deleted, and value, which is the string value set by the node group for this parameter (the value is duplicated for convenience; also appears in the classes object).
variables

An object that defines the values of any top-level variables set by the node group. The object is a mapping between variable names and their values (which can be any JSON value).
children A JSON array containing node group objects for the group's immediate children. Grandchildren are represented in additional nested children arrays. If you included a depth in your request, the amount of nesting stops at the specified depth.
immediate_child_count The number of immediate children of the group. Child count reflects the number of children that exist in the classifier, not the number that are returned in the request, which can vary based on permissions and query parameters.

The following example is a response to a request for the first two levels of children under the root group, All Nodes. The user has permission to view only child-1 and grandchild-5, which limits the response to child-1, the first children of child-1, and grandchild-5. No additional grandchildren are represented because the request specified depth=2.

[
    {
        "name": "child-1",
        "id": "652227cd-af24-4fd8-96d4-b9b55ca28efb",
        "parent": "00000000-0000-4000-8000-000000000000",
        "environment_trumps": false,
        "rule": ["and", ["=", ["fact", "foo"], "bar"], ["not", ["<", ["fact", "uptime_days"], "31"]]],
        "variables": {},
        "environment": "test",
        "classes": {},
        "children": [
            {
                "name": "grandchild-1",
                "id": "a3d976ad-51d3-4a29-af57-09990f3a2481",
                "parent": "652227cd-af24-4fd8-96d4-b9b55ca28efb",
                "environment_trumps": false,
                "rule": ["and", ["=", ["fact", "foo"], "bar"], ["or", ["~", "name", "db"], ["<", ["fact", "processorcount"], "9"], ["=", ["fact", "operatingsystem"], "Ubuntu"]]],
                "variables": {},
                "environment": "test",
                "classes": {},
                "children": [],
                "immediate_child_count": 0
            },
            {
                "name": "grandchild-2",
                "id": "71905c11-5295-41cf-a143-31b278cfc859",
                "parent": "652227cd-af24-4fd8-96d4-b9b55ca28efb",
                "environment_trumps": false,
                "rule": ["and", ["=", ["fact", "foo"], "bar"], ["not", ["~", ["fact", "kernel"], "SunOS"]]],
                "variables": {},
                "environment": "test",
                "classes": {},
                "children": [],
                "immediate_child_count": 0
            }
        ],
        "immediate_child_count": 2
    },
    {
        "name": "grandchild-5",
        "id": "0bb94f26-2955-4adc-8460-f5ce244d5118",
        "parent": "0960f75e-cdd0-4966-96f6-5e60948a7217",
        "environment_trumps": false,
        "rule": ["and", ["=", ["fact", "foo"], "bar"], ["and", ["<", ["fact", "processorcount"], "16"], [">=", ["fact", "kernelmajversion"], "2"]]],
        "variables": {},
        "environment": "test",
        "classes": {},
        "children": [],
        "immediate_child_count": 0
    }
]

Error responses

If there is an error, Node classifier API errors provide error information in the kind key.

If the supplied node group ID is not a valid UUID, the server returns a 400 Bad Request malformed-UUID response.

If the value of depth is not an integer, or it is a negative integer, the server returns a 400 Bad Request malformed-number or 400 Bad Request illegal-count response.

If the endpoint can't find a node group with the specified ID, the server returns a 400 Not Found response.