Groups endpoint examples

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

Get a list of all node groups and their IDs

Use this curl command to get a list of 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)"

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

The response is a list of all node groups and their IDs, for example:
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

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.

You only need to include new nodes, although it does not hurt to include previously-pinned nodes.

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