media server logo
PricingSign inStart in the cloud for free
API docsOverview
General settings
Ports
Cluster nodes
Additional utilities
Storages
Toggle documentation navigation
Callaba home

Cluster nodes

Use Cluster nodes to attach, activate, inspect, and remove Engine instances in a multi-node Callaba deployment.

What it doesAdd capacity to a cluster

Choose this whenOne deployment needs trusted regional or additional Engine nodes.

Use another module whenUse a single Engine instance when distributed capacity or regional placement is not required.

1Register a node2Synchronize state3Serve workload
POST /api/clusterNodes/create
10 endpoints

Before you start

All methods require an administrative x-access-token. Nodes must be reachable over the required network paths, use the intended role, and have unique identity and address information.

What you can do

  • create, update, getAll, getCount, and getById manage node records.
  • attachNode and detachNode change cluster membership.
  • start and stop control a registered node.
  • remove deletes a node record that is no longer needed.

Example workflow

  1. Create the node with its role and reachable address.
  2. Attach it to the intended cluster.
  3. Start it and verify its state before assigning work.
  4. Stop and detach it before maintenance or removal.

Common use cases

  • Add a regional processing node for an event near its contribution feeds.
  • Keep a test node separate from production assignments.
  • Drain and detach a node for maintenance without deleting the cluster.

Limits and troubleshooting

Incorrect roles, duplicate addresses, unreachable hosts, or missing network permissions can prevent attachment or startup. Detaching or stopping a node can affect resources assigned to it, so move or stop dependent work first.

Next steps

After the node is active, create the ingest or processing resources that should run on the cluster.

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.

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
Copy code
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
Copy code
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
Copy code
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
Copy code
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
JSON
Copy code
{
  "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
Back toPortsNext toAdditional utilities