Dynamic Group Primitives

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, hardware, or other 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 primitive or the name of the primitive as given in the "name" field.

Data Fields

The DynGroups fields are:

name
     Required: The name for the Dynamic Group. Names cannot start with a number.

selector
     Required: A string representing a node selector function

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. For example, since a node’s boot configuration is set in the _boot_config attribute, the following selects all nodes that using DefaultBoot:

a[_boot_config]=="DefaultBoot"

In this example, a[..] looks up an attribute. Similarly, h[..] can be used for hardware, n[..] for node field, and s[..] for status.

For example, the amount of total memory on a node is given in the hardware information with the ram_total key. Using the following returns the set of nodes with more than 1000000 bytes of memory:

h[ram_total] > 100000

See Node Selectors for more information.

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}