Callaba
Callaba home

Cluster nodes

Use Cluster nodes to register, attach, start, inspect, stop, detach, and remove Engine nodes. All methods require an administrative x-access-token.

Membership lifecycle

Create the node with its intended role and reachable address, attach it, then start it and verify its state before assigning work. Stop and detach a node before maintenance or removal.

Incorrect roles, duplicate addresses, unreachable hosts, or missing network permissions can prevent attachment or startup. Move or stop dependent resources before changing a node that serves them.

10 endpoints
POST
/api/clusterNodes/create
Admin token required

Use this method to register a new internal node in the cluster. In production, the create call matters when the fleet is expanding, when a child node should become part of the trusted topology, or when a clean test node should be prepared ahead of a rollout.

For slave nodes, the child-node API token is part of that trust handshake. The dashboard also warns the operator not to use a public IP here because this relationship is intended for internal infrastructure.

Primary control node

Use this when one internal node should act as the main coordination point for the cluster and the rest of the fleet should align around it.

Primary control node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Primary cluster node",
  "host": "10.20.0.10",
  "node_type": "CLUSTER_NODES_TYPE_MASTER",
  "active": true
}'
Connected slave node

Use this when a child node should join the trusted internal fleet and needs the child-node API token so attachment can succeed cleanly.

Connected slave node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}'
Test or validation node

Use this when a node should be provisioned for validation, rehearsal, or isolated checks before it becomes part of a production path.

Test or validation node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Test validation node",
  "host": "10.20.0.40",
  "node_type": "CLUSTER_NODES_TYPE_TEST",
  "active": false
}'
Request body parameters
Identity
name
string
Copy direct link

Dashboard label: Node name.

Human-readable internal node name.

node_type
string
Copy direct link

Dashboard label: Type.

Real product values are CLUSTER_NODES_TYPE_MASTER, CLUSTER_NODES_TYPE_SLAVE, and CLUSTER_NODES_TYPE_TEST.

Connectivity
host
string
Copy direct link

Dashboard label: Host.

Internal node address. The dashboard warns operators not to use a public IP here.

Trust
api_token
string
Copy direct link

Dashboard label: API token.

Child-node JWT token used for slave-node attachment flows. It is only relevant when the node type is CLUSTER_NODES_TYPE_SLAVE.

Runtime
active
boolean
Copy direct link

Dashboard label: Enabled.

Controls whether the node should be active right after provisioning.

Create cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}'
Response
success
boolean
Copy direct link

The create call confirms acceptance with a success-shaped response.

Response: Create cluster node
{
  "success": true
}
POST
/api/clusterNodes/getCount
Admin token required
POST
/api/clusterNodes/getAll
Admin token required
POST
/api/clusterNodes/getById
Admin token required
POST
/api/clusterNodes/update
Admin token required
POST
/api/clusterNodes/start
Admin token required
POST
/api/clusterNodes/stop
Admin token required
POST
/api/clusterNodes/attachNode
Admin token required
POST
/api/clusterNodes/detachNode
Admin token required
DELETE
/api/clusterNodes/remove
Admin token required
Workflow examples and help
REST solution recipe

Attach a worker to a Callaba cluster

Create the node record, attach it to the reviewed master, and start it only after network and version checks pass.

  1. Create the nodeRegister the reviewed host and role.POST /api/clusterNodes/create
  2. Attach itJoin the node to the intended cluster relationship.POST /api/clusterNodes/attachNode
  3. Start the workerStart only after the attachment and health checks succeed.POST /api/clusterNodes/start

Cluster methods require administrative access. Test reachability and compatibility before moving production workloads.

Ask AI