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.
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.
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.
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
}'Use this when a child node should join the trusted internal fleet and needs the child-node API token so attachment can succeed cleanly.
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
}'Use this when a node should be provisioned for validation, rehearsal, or isolated checks before it becomes part of a production path.
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
}'Dashboard label: Node name.
Human-readable internal node name.
Dashboard label: Type.
Real product values are CLUSTER_NODES_TYPE_MASTER, CLUSTER_NODES_TYPE_SLAVE, and CLUSTER_NODES_TYPE_TEST.
Dashboard label: Host.
Internal node address. The dashboard warns operators not to use a public IP here.
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.
Dashboard label: Enabled.
Controls whether the node should be active right after provisioning.
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
}'The create call confirms acceptance with a success-shaped response.
{
"success": true
}Workflow examples and help
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.
- Create the nodeRegister the reviewed host and role.
POST /api/clusterNodes/create - Attach itJoin the node to the intended cluster relationship.
POST /api/clusterNodes/attachNode - 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.