State Map Primitives

A State Map is a set of criteria that are used to identify groups of nodes in a given state. The states maps primitive is accessed through the /nodes/waitfor URL, but is otherwise analogous to the other endpoints. Several endpoints provide for the creation and modification of state maps.

Data Fields

The state map fields 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 ClusterWare database.

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

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

Non-persistent state maps expire after 10 seconds unless extended with one or more PUT calls.

Additional Endpoints

Several additional endpoints are available:

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

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

GET /nodes/waitfor/<NAME>
Returns detailed information for 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 will extend
the expiration time for a non-persistent state map

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

GET /nodes/waitfor/<NAME>/nodes
Returns a list of nodes currently in the 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"}

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 expression 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"}}

Get the lists of nodes that match each state expression 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}

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