Groups endpoint examples

We've updated our documentation to remove harmful terminology.
Sections

Use example requests to better understand how to work with groups in the node classifier API.

These requests assume the following configuration:

  • The Puppet primary server is running on puppetlabs-nc.example.vm and can allow certificates to enable URL requests.
  • Port 4433 is open.

Create a group called My Nodes

This request uses POST /v1/groups to create 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"

See Usage notes for curl examples for information about forming curl commands.

Get the group ID of My Nodes

This request uses the groups endpoint to get details about groups.

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"

See Usage notes for curl examples for information about forming curl commands.

The response is a JSON file containing details about all groups, including the My Nodes group ID.

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

Pin a node to the My Nodes group

This request uses POST /v1/groups/<id> to pin the node example-to-pin.example.vm to My Groups using the group ID retrieved in the previous step.

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 --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

See Usage notes for curl examples for information about forming curl commands.

Pin a second node to the My Nodes group

This request uses POST /v1/groups/<id> to pin a second node example-to-pin-2.example.vm to My Groups.

Note: You must supply all the nodes to pin to the group. For example, this request includes both example-to-pin.example.vm and example-to-pin-2.example.vm.
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", "example-to-pin-2.example.vm"] }'

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

See Usage notes for curl examples for information about forming curl commands.

Unpin a node from the My Nodes group

This request uses POST /v1/groups/<id> to unpin the node example-to-unpin.example.vm from My Groups.

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/a02ee4a7-8ec1-44ec-99a6-ef362596fd6e/unpin"
data='{ "nodes": ["example-to-unpin"] }'

curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key "$key" --request POST "$uri" --data "$data"

See Usage notes for curl examples for information about forming curl commands.

Add a class and parameters to the My Nodes group

This request uses POST /v1/groups/<id> to specify the apache class and parameters for My Groups.

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"

See Usage notes for curl examples for information about forming curl commands.

How helpful was this page?

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.