POST /v1/groups/<id>

Edit the name, environment, parent node group, rules, classes, class parameters, configuration data, and variables for a specific node group.

Request format

When Forming node classifier API requests to this endpoint, the body must be a JSON object describing the changes you want to make to the node group. For a complete list of keys you can include in the request, refer to POST /v1/groups.

If your request includes classes, config_data, variables, and rule keys, these values are merged with the node group's existing values. Any keys in the resulting combined object with a null value are removed. To remove classes, class parameters, configuration data, variables, or rules from the node group, set the key to null in the change request.

If the request supplies a rule key that is set to a new value or nil, the rule is updated wholesale or removed from the group, depending on the supplied value.

If the request contains the name, environment, description, or parent keys, then these values replace the old values entirely.

The serial_number key is optional. If your request includes a serial_number that does not match the group's current serial number, the service returns a 409 Conflict response. To bypass this check, omit the serial_number key from the request.

The following code examples show a node group, the change request, and the end result (where the changes are merged into the node group's settings).

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.

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.

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"

Error responses

If there is an error, Node classifier API errors provide error information in the kind key and are similar to the POST /v1/groups error responses.

You can't edit the root All Nodes node group’s rule. Attempting o do so returns a 422 Unprocessable Entity response.