State Map Primitives#

A State Map is a set of criteria that are used to identify groups of nodes in a given state. The state maps primitive is accessed through the /nodes/waitfor URL and through the /statemaps URL.

/nodes/waitfor allows you to complete most of the same actions as /statemaps and the two can be used interchangeably to modify the same persistent state map, if needed. In addition, /nodes/waitfor has the ability to:

  • Create a non-persistent state map by omitting the name field.

  • Extend state map activation.

Data Fields#

The state map fields using /nodes/waitfor are:

name
 Optional: The name for the state map. Names cannot start with a number. If
 no name is given, a random string is chosen and that state map is not
 persisted in the ClusterWareAI database.

states
 Required: A dictionary of state-names and their corresponding node-selector

For example, POST /nodes/waitfor creates a new state map. To completely replace the list of states, use the PATCH /nodes/waitfor action with the “states” key.

State maps expire after 10 seconds unless extended with one or more PUT /nodes/waitfor/<NAME> calls. Temporary state maps are removed after expiring. Persistent state maps are deactivated after expiring, but can be reactivated later.

The state map fields using /statemaps are:

name
 Required: The name for the state map. Names cannot start with a number.

description
  Optional: A text string with descriptive information

states
 Required: A dictionary of state-names and their corresponding node-selector

For example, POST /statemaps creates a new state map.

Additional Endpoints#

Several additional endpoints are available:

GET /nodes/waitfor
GET /statemaps
Returns a list of state maps (UIDs) that are currently defined

GET /statemaps/meta
Returns the meta information about state map fields

GET /nodes/waitfor/<NAME>/nodes
GET /statemap/<NAME>/nodes
Returns a list of nodes currently in the given state map

POST /nodes/waitfor
POST /statemaps
Create a new state map with the posted parameters

GET /nodes/waitfor/<NAME>
GET /statemap/<NAME>
Returns detailed information for a given state map (by Name or UID)

PUT /statemap/<NAME>/activate
Activate a given state map (by Name or UID)

PUT /nodes/waitfor/<NAME>
Update the expiration for a given state map (by Name or UID);
accepts a parameter ``duration`` which extends
the expiration time for a non-persistent state map

PATCH /statemap/<NAME>
Update state map details.

DELETE /nodes/waitfor/<NAME>
Deletes a given state map

Example#

Create a new, persistent state map:

curl -X POST https://head1.cluster.local/api/v1/nodes/waitfor \
  --data '{"name":"my_states", "states": { "red_state": "index > 10" } }' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
  {"success": true, "data": "my_states"}

curl -X POST https://head1.cluster.local/api/v1/statemaps \
  --data '{"name":"my_states", "states": { "red_state": "index > 10" } }' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
  {"success": true, "data": "my_states"}

Create a new, non-persistent state map:

curl -X POST https://head1.cluster.local/api/v1/nodes/waitfor \
  --data '{"states": { "blue_state": "index < 10" } }' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
  {"success": true, "data": "UAV2ShNEW1265rCR"}

Get the state information on a state map:

curl -X GET https://head1.cluster.local/api/v1/nodes/waitfor/my_states \
 -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
 {"success": true, "data": {"red_state": "index>10"}}

curl -X GET https://head1.cluster.local/api/v1/statemap/my_states \
 -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
 {"success": true, "data": {"red_state": "index>10"}}

Get the lists of nodes that match each state in a state map:

curl -X GET https://head1.cluster.local/api/v1/nodes/waitfor/UAV2ShNEW1265rCR/nodes \
 -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
 {"success": true, "data": {"blue_state": ["e992a2b610e746db9cbcffa18656c631", "d6a9497dab1e44eeb892b6ed068c8f0b", "9bfc8ecc32934a83b1de64273f717d3f"]}}

Delete the state map:

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

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

Extend a non-persistent state map by 30 seconds:

curl -X POST https://head1.cluster.local/api/v1/nodes/waitfor/UAV2ShNEW1265rCR \
  --data '{"duration": 30}' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
  {"success": true, "data": {"blue_state": ["e992a2b610e746db9cbcffa18656c631", "d6a9497dab1e44eeb892b6ed068c8f0b", "9bfc8ecc32934a83b1de64273f717d3f"]}}

A successful return includes a list of node UIDs for each of the states.