GET /v1/groups

Retrieves a list of all node groups in the node classifier.

Request format

When Forming node classifier API requests to this endpoint, you can append the inherited parameter to the URI path. If this parameter is set to any value besides 0 or false, the response includes the classes, class parameters, configuration data, and variables that each group inherits from its ancestor groups.

For example, this request does not specify the inherited parameter:

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" "$uri"

Use the following curl command to get a pared-down response that lists all node groups and their corresponding IDs. Node group IDs are useful when running tasks or plans.

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups"
curl --silent --header "$auth_header" "$uri" | jq -M -r '.[] | "\(.name) \(.id)"'

The response is more simplified than the full response to the standard GET /v1/groups request:

All Nodes 00000000-0000-4000-8000-000000000000
PE Master 07002034-c20f-44de-97d2-f72d03e481fb
Development one-time run exception 124a11d8-b912-45f0-9a6d-5ddd81aaa0ed
PE PuppetDB 289f176b-1c30-4e85-ad07-131e55f29354
PE Database 28b78e75-3b7e-464e-8f02-29a80b88fe02
Development environment 388f2eea-2f91-4ed7-8f84-93d8bf115ec5
PE Orchestrator 3f490039-395f-4c87-8dfb-f72d03e481fb
Production environment 43d438de-78da-4186-9405-e3f743989a5c
All Environments 6a10e0eb-ab6b-4ba7-b637-28fdf91ed659
PE Compiler 9cab6f77-f0cf-4c0e-b2ce-6aa6a2489c71
PE Infrastructure 9cd74d7e-6fb7-4d17-9cd8-e3f743989a5c
PE Patch Management aae9e4cd-fed5-4f07-8149-98a699a3b692
PE Certificate Authority d4065370-0cab-43cf-a4fa-93d8bf115ec5
PE Agent d4cf6659-6fc8-4419-b2a2-28fdf91jh9607
PE Console de97e269-4a9e-4f3d-a931-39993b0ef3f6
PE Infrastructure Agent e46543a6-61c6-49f2-865f-28fdf91ed659

Response format

A successful response is a JSON array of node group objects using 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.
`config_data`	An object similar to the `classes` object that specifies parameters that are applied to classes if the class is assigned in the classifier or in Puppet code. 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 group sets for that parameter, which is always a string. This feature is enabled or disabled through the `classifier::allow-config-data` setting. When set to `false`, this key is omitted.
`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).
`last_edited`	The most recent time at which a user committed changes to a node group. This is a time stamp in ISO 8601 format, `YYYY-MM-DDTHH:MM:SSZ`.
`serial_number`	A number assigned to a node group. This number is incremented each time changes to a group are committed. `serial_number` is used to prevent conflicts when multiple users make changes to the same node group at the same time.

For example, this response describes a single node group:

{
  "environment_trumps": false,
  "parent": "00000000-0000-4000-8000-000000000000",
  "name": "My Nodes",
  "variables": {},
  "id": "085e2797-32f3-4920-9412-8e9decf4ef65",
  "environment": "production",
  "classes": {}
}

This example also describes a single node group, but with more information:

{
  "name": "Webservers",
  "id": "fc500c43-5065-469b-91fc-37ed0e500e81",
  "last_edited": "2018-02-20T02:36:17.776Z",
  "serial_number": 16,
  "environment": "production",
  "description": "This group captures configuration relevant to all web-facing production webservers, regardless of location.",
  "parent": "00000000-0000-4000-8000-000000000000",
  "rule": ["and", ["~", ["trusted", "certname"], "www"],
                  [">=", ["fact", "total_ram"], "512"]],
  "classes": {
    "apache": {
      "serveradmin": "bofh@travaglia.net",
      "keepalive_timeout": "5"
    }
  },
  "config_data": {
    "puppet_enterprise::profile::console": {"certname": "console.example.com"},
    "puppet_enterprise::profile::puppetdb": {"listen_address": "0.0.0.0"}
  },
  "variables": {
    "ntp_servers": ["0.us.pool.ntp.org", "1.us.pool.ntp.org", "2.us.pool.ntp.org"]
  }
}

This example includes classes and parameters that have been deleted:

{
  "name": "Spaceship",
  "id": "fc500c43-5065-469b-91fc-37ed0e500e81",
  "last_edited": "2018-03-13T21:37:03.608Z",
  "serial_number": 42,
  "environment": "space",
  "parent": "00000000-0000-4000-8000-000000000000",
  "rule": ["=", ["fact", "is_spaceship"], "true"],
  "classes": {
    "payload": {
      "type": "cubesat",
      "count": "8",
      "mass": "10.64"
    },
    "rocket": {
      "stages": "3"
    }
  },
  "deleted": {
    "payload": {"puppetlabs.classifier/deleted": true},
    "rocket": {
      "puppetlabs.classifier/deleted": false,
      "stages": {
        "puppetlabs.classifier/deleted": true,
        "value": "3"
      }
    }
  },
  "variables": {}
}

In the above example, the entire payload class has been deleted, because the puppetlabs.classifier/deleted key maps to true. This is in contrast to the rocket class, which has had only its stages parameter deleted.