Groups endpoint

Query parameters

The request accepts these parameters.

Response format

The response is a JSON array of node group objects, using these keys:

This example shows a node group object:

{
  "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 shows a node group object that refers to some 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": {}
}

The entire payload class has been deleted, because its deleted parameters object's puppetlabs.classifier/deleted key maps to true, in contrast to the rocket class, which has had only its stages parameter deleted.

Rule condition grammar

Nodes can be classified into groups using rules. This example shows how rule conditions must be structured:

    condition  : [ {bool} {condition}+ ] | [ "not" {condition} ] | {operation}
         bool  : "and" | "or"
    operation  : [ {operator} {fact-path} {value} ]
     operator  : "=" | "~" | ">" | ">=" | "<" | "<="
    fact-path  : {field-name} | [ {path-type} {field-name} {path-component}+ ]
    path-type  : "trusted" | "fact"
path-component : field-name | number
    field-name : string

For the regex operator "~", the value is interpreted as a Java regular expression. Literal backslashes must be used to escape regex characters in order to match those characters in the fact value.

For the numeric comparison operators (">", ">=", "<", and "<="), the fact value (which is always a string) is coerced to a number (either integral or floating-point). If the value can't be coerced to a number, the numeric operation evaluates to false.

For the fact path, the rule can be either a string representing a top level field (the only current meaningful value here would be "name" representing the node name) or a list of strings and indices that represent looking up a field in a nested data structure. When passing a list of strings or indices, the first and second entries in the list must be strings. Subsequent entries can be indices.

Regular facts start with "fact" (for example, ["fact", "architecture"]) and trusted facts start with "trusted" (for example, ["trusted", "certname"]).

Error responses

serial_number

If you commit a node group with a serial_number that an API call has previously assigned, the service returns a 409 Conflict response.

Request format

The request body must be a JSON object describing the node group to be created. The request uses these keys:

Response format

If the node group was successfully created, the service returns a 303 See Other response, with the path to retrieve the created node group in the "location" header of the response.

Error responses

Responses and keys returned for create group requests depend on the type of error.

schema-violation

malformed-request

uniqueness-violation

missing-referents

missing-parent

If the parent of the node group does not exist, the service returns a 422 Unprocessable Entity response. The response object uses these keys:

inheritance-cycle

If the request causes an inheritance cycle, the service returns a 422 Unprocessable Entity response. The response object uses these keys:

Response format

The response is a JSON array of node group objects, using these keys:

Error responses

If the node group with the given ID cannot be found, the service returns 404 Not Found and malformed-uuid responses . The body includes a generic 404 error response as described in the errors documentation.

serial_number

If you commit a node group with a serial_number that an API call has previously assigned, the service returns a 409 Conflict response.

Request format

The request body must be a JSON object describing the node group to be created. The request uses these keys:

Response format

If the node group is successfully created, the service returns a 201 Created response, with the node group object (in JSON) as the body. If the node group already exists and is identical to the submitted node group, then the service takes no action and returns a 200 OK response, again with the node group object as the body.

Error responses

If the requested node group object contains the id key, and its value differs from the UUID specified in the request's path, the service returns a 400 Bad Request response.

In addition, this operation can produce the general malformed-error response and any response that could also be generated by the POST group creation endpoint.

Request format

The request body must be JSON object describing the delta to be applied to the node group.

The classes, config_data, variables, and rule keys of the delta are merged with the node group, and then any keys of the resulting object that have a null value are deleted. This allows you to remove classes, class parameters, configuration data, variables, or the rule from the node group by setting them to null in the delta.

If the delta has a rule key that’s set to a new value or nil, it's updated wholesale or removed from the group accordingly.

The name, environment, description, and parent keys, if present in the delta, replace the old values wholesale with their values.

The serial_number key is optional. If you update a node group and provide the serial_number in the payload, and the serial_number is not the current one for that group, the service returns a 409 Conflict response. To bypass this check, omit the serial_number.

Note that the root group’s rule cannot be edited; any attempts to do so raise a 422 Unprocessable Entity response.

In the following examples, a delta is merged with a node group to update the group.

{
  "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"]
  }
}

{
  "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"]
  }
}

{
  "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"]
  }
}

Deleted classes and class parameters

If the node group definition contains classes and parameters that have been deleted it is still possible to update the node group with those parameters and classes. Updates that don’t increase the number of errors associated with a node group are allowed.

Error responses

The response object uses these keys:

If the requested node group object contains the id key, and its value differs from the UUID specified in the request’s path, the service returns a 400 Bad Request response.

In addition, this operation can produce the general malformed-error response and any response that could also be generated by the POST group creation endpoint.

422 responses to POST requests can include errors that were caused by the node group’s children, but a node group being created with a PUT request cannot have any children.

Response format

If the delete operation is successful, the sever returns a 204 No Content response.

Error responses

In addition to the general malformed-uuid response, if the node group with the given ID does not exist, the service returns a 404 Not Found response, as described in the errors documentation.

children-present

The service returns a 422 Unprocessable Entity and rejects the delete request if the node group that is being deleted has children.

The response object uses these keys:

Request format

You can provide the names of the nodes to pin in two ways.

• As the value of the nodes query parameter. For multiple nodes, use a comma-separated list format.

  For example:

  POST /v1/groups/58463036-0efa-4365-b367-b5401c0711d3/pin?nodes=foo%2Cbar%2Cbaz

  This request pins the nodes foo, bar, and baz to the group.

• In the body of a request. In the nodes field of a JSON object, specify the node name as the value. For multiple nodes, use a JSON array.

  For example:

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

  This request pins the nodes foo, bar, and baz to the group.

It's easier to use the query parameter method. However, if you want to affect a large number of nodes at once, the query string might get truncated. Strings are truncated if they exceed 8,000 characters. In such cases, use the second method. The request body in the second method is allowed to be many megabytes in size.

Response format

If the pin is successful, the service returns a 204 No Content response with an empty body.

Error responses

This endpoint uses the following error responses.

If you don't supply the nodes query parameter or a request body, the service returns a 400 Malformed Request response, using these keys:

If you supply a request body that is not valid JSON, the service returns a 400 Malformed Request response. The response object uses these keys:

If the request's body is valid JSON, but the payload is not an object with just the nodes field and no other fields, the service returns a 400 Malformed Request response. The response object uses these keys:

Request format

You can provide the names of the nodes to pin in two ways.

• As the value of the nodes query parameter. For multiple nodes, use a comma-separated list format.

  For example:

  POST /v1/groups/58463036-0efa-4365-b367-b5401c0711d3/unpin?nodes=foo%2Cbar%2Cbaz

  This request unpins the nodes foo, bar, and baz from the group. If any of the specified nodes were not pinned to the group, they are ignored.

• In the body of a request. In the nodes field of a JSON object, specify the node name as the value. For multiple nodes, use a JSON array.

  For example:

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

  This request unpins the nodes foo, bar, and baz from the group. If any of the specified nodes were not pinned to the group, they are ignored.

It's easier to use the query parameter method. However, if you want to affect a large number of nodes at once, the query string might get truncated. Strings are truncated if they exceed 8,000 characters. In such cases, use the second method. The request body in the second method is allowed to be many megabytes in size.

Response format

If the unpin is successful, the service returns a 204 No Content response with an empty body.

Error responses

If you don't supply the nodes query parameter or a request body, the service returns a 400 Malformed Request response. The response object uses these keys:

If a request body is supplied but it is not valid JSON, the service returns a 400 Malformed Request response. The response object uses these keys:

If the request's body is valid JSON, but the payload is not an object with just the nodes field and no other fields, the service returns a 400 Malformed Request response. The response object uses these keys:

Response format

{
  "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
      ]
    ]
  }
}

Error responses

In addition to the general malformed-uuid error response, if the group with the given ID cannot be found, a 404 Not Found response is returned.