Dynamic Group Objects

Where Attribute Groups require intentional effort to join or leave, Dynamic Groups (DynGroups) are a way to group nodes based on shared or common attributes, status, or hardware information. DynGroups also do not alter a node’s attributes, so they are most useful in targeting an action at a group of similar nodes.

When issuing requests, the UID field in the URL can be either the actual UID of the object or the name of the object as given in the "name" field.

Data Fields

The DynGroups fields are:

name
     Required: The name for the Dynamic Group

selector
     Required: A string representing a node-selector function (see below)

description
     Optional: A text string with descriptive information

A node-selector function is a logical function that is computed based on a given node’s information. Since a node’s boot configuration is set in the _boot_config attribute, the following will select all nodes that using DefaultBoot:

a[_boot_config]=="DefaultBoot"

the a[..] means to look up a nodes attribute, similarly h[..] can be used for hardware and s[..] for status. The amount of total memory on a node is given in the hardware information, under the ram_total key:

h[ram_total] > 100000

will give the set of nodes with more than 1000000 bytes of memory.

See Attribute Groups and Dynamic Groups for more information on the node-selector language.

Additional Endpoints

To find the set of nodes that are currently in a given DynGroup, use the following endpoint:

GET /dyngroup/<UID>/nodes
     Returns a JSON object with a list of node UIDs; if no nodes are currently in the
     dynamic group, an empty list will be returned

Example

Create a dynamic group:

curl -X POST https://head1.cluster.local/api/v1/dyngroups --data \
    '{"name":"BigMemory","selector":"h[ram_total] > 100GB"}'
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "b30886d9c8ca40d99d66b668074811b1"}

Verify the group’s information:

curl -X GET https://head1.cluster.local/api/v1/dyngroup/BigMemory -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"name": "BigMemory", "selector": "h[ram_total] > 100GB", \
    "parsed": "(hardware[\"ram_total\"] > 100GB)", "last_modified": 1721930148.843629, \
    "last_modified_on": "head23.cluster.local", "last_modified_by": "admin1", \
    "uid": "b30886d9c8ca40d99d66b668074811b1"}}

Get the list of nodes currently in this DynGroup:

curl -X GET https://head1.cluster.local/api/v1/dyngroup/BigMemory/nodes -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": ["199eadbea2084b80a4efcf445538efc5", \
    "d3b59618750e4957bc3139a0a29cb1a8", "4343fc9a431d49e89639b8cf3644db9a", \
    "9e831349cbcf484f8db075e12ef4dd9d", "35d6faece6a7411cb26a7c7b02fda708"]}

Delete the DynGroup:

curl -X DELETE https://head1.cluster.local/api/v1/dyngroup/BigMemory -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}