Groups endpoints

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"

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)"'

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

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.

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":{}}. Note: 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"

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 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.

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

GET https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65

The request 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.

The original node group settings:

{
  "name": "Webservers",
  "id": "58463036-0efa-4365-b367-b5401c0711d3",
  "environment": "staging",
  "parent": "00000000-0000-4000-8000-000000000000",
  "rule": ["~", ["trusted", "certname"], "www"],
  "classes": {
    "apache": {
      "serveradmin": "bofh@travaglia.net",
      "keepalive_timeout": 5
    },
    "ssl": {
      "keystore": "/etc/ssl/keystore"
    }
  },
  "variables": {
    "ntp_servers": ["0.us.pool.ntp.org", "1.us.pool.ntp.org", "2.us.pool.ntp.org"]
  }
}

The change request:

{
  "name": "Production Webservers",
  "id": "58463036-0efa-4365-b367-b5401c0711d3",
  "environment": "production",
  "parent": "01522c99-627c-4a07-b28e-a25dd563d756",
  "classes": {
    "apache": {
      "serveradmin": "roy@reynholm.co.uk",
      "keepalive_timeout": null
    },
    "ssl": null
  },
  "variables": {
    "dns_servers": ["dns.reynholm.co.uk"]
  }
}

The updated group settings:

{
  "name": "Production Webservers",
  "id": "58463036-0efa-4365-b367-b5401c0711d3",
  "environment": "production",
  "parent": "01522c99-627c-4a07-b28e-a25dd563d756",
  "rule": ["~", ["trusted", "certname"], "www"],
  "classes": {
    "apache": {
      "serveradmin": "roy@reynholm.co.uk"
    }
  },
  "variables": {
    "ntp_servers": ["0.us.pool.ntp.org", "1.us.pool.ntp.org", "2.us.pool.ntp.org"],
    "dns_servers": ["dns.reynholm.co.uk"]
  }
}

In the above example, the ssl class was deleted because its entire object was mapped to null, whereas, for the apache class, only the keepalive_timeout parameter was deleted.

Here is an example of a complete curl request to the POST /v1/groups/<id> endpoint:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65"
data='{"classes": 
          {"apache": {
               "serveradmin": "bob@example.com",
               "keepalive_timeout": null}
          }
      }'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

DELETE https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin

The request must also provide the names of the nodes you want to pin to the group. There are two ways to do this:

• Append the node names to the URI path. If you are pinning more than one node, use encoded comma separation (%2C) between node names. For example, this request pins the nodes named foo, bar, and baz to the group:

  POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin?nodes=foo%2Cbar%2Cbaz

• Supply the node names in the request body. For a single node, you can supply this in a simple JSON object. For multiple nodes, supply the node names in an array. For example, this JSON body pins a single node:

  {"nodes": ["foo"]}

  And this body pins three nodes:

  {"nodes": ["foo", "bar", "baz"]}

Here is an example of a complete curl request to the POST /v1/groups/<id>/pin endpoint. If necessary, replace /etc/puppetlabs/puppet/ssl/certs/ca.pem with the correct path to your CA certificate file:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin"
data='{ "nodes": ["example-to-pin.example.vm"] }'

curl --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/unpin

The request must also provide the names of the nodes you want to unpin from the group. There are two ways to do this:

• Append the node names to the URI path. If you are unpinning more than one node, use encoded comma separation (%2C) between node names. For example, this request unpins the nodes named foo, bar, and baz from the group:

  POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/unpin?nodes=foo%2Cbar%2Cbaz

• Supply the node names in the request body. For a single node, you can supply this in a simple JSON object. For multiple nodes, supply the node names in an array. For example, this JSON body unpins a single node:

  {"nodes": ["foo"]}

  And this body unpins three nodes:

  {"nodes": ["foo", "bar", "baz"]}

Here is an example of a complete curl request to the POST /v1/groups/<id>/pin endpoint:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/unpin"
data='{ "nodes": ["example-to-unpin"] }'

curl --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

GET https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/rules

A successful response returns a JSON object that uses these keys to enumerate the group's rules:

Key	Definition
rule	The rules for the group in classifier format.
rule_with_inherited	The inherited rules (including the rules for this group) in classifier format
translated	An object containing two children (nodes_query_format and inventory_query_format), which represent each of the inherited rules translated into a different format.
nodes_query_format	The optimized translated inherited group in the format that works with the nodes endpoint in PuppetDB.
inventory_query_format	The optimized translated inherited group in the format that works with the inventory endpoint in PuppetDB.

For example:

{
  "rule": [
    "=",
    [
      "fact",
      "is_spaceship"
    ],
    "true"
  ],
  "rule_with_inherited": [
    "and",
    [
      "=",
      [
        "fact",
        "is_spaceship"
      ],
      "true"
    ],
    [
      "~",
      "name",
      ".*"
    ]
  ],
  "translated": {
    "nodes_query_format": [
      "or",
      [
        "=",
        [
          "fact",
          "is_spaceship"
        ],
        "true"
      ],
      [
        "=",
        [
          "fact",
          "is_spaceship",
          true
        ]
      ]
    ],
    "inventory_query_format": [
      "or",
      [
        "=",
        "facts.is_spaceship",
        "true"
      ],
      [
        "=",
        "facts.is_spaceship",
        true
      ]
    ]
  }
}