Cluster management is now scriptable

Until now, rebalancing replicas and scaling your cluster meant clicking through the UI. Now you can do it from a script.

Three new API endpoints let you rebalance traffic weights, add replicas, and remove replicas. Same operations as the UI, but automatable.

The endpoints

We added three endpoints to manage replica topology and traffic distribution:

PUT /v0/organizations/{organization_id}/clusters/{cluster_id}/weights to request a manual rebalance.
POST /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas to add a new replica and assign initial weights.
DELETE /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas/{replica_name} to remove a replica and rebalance traffic.

Note that API calls require an old_weights field to prevent conflicts from concurrent modifications. You must first GET the current configuration from the /v0/organizations/<organization_id>/clusters-configuration endpoint and use the returned weights when you add, delete, or rebalance replicas.

Rebalance replica weights

Use this endpoint when you want to redistribute read/write traffic across existing replicas.

curl -X PUT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  "https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/weights" \
  -d '{
    "old_weights": {
      "copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
      "writer": {"<replica-1-name>": 100, "<replica-2-name>": 0},
      "reader": {"<replica-1-name>": 100, "<replica-2-name>": 0}
    },
    "new_weights": {
      "copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
      "writer": {"<replica-1-name>": 50, "<replica-2-name>": 50},
      "reader": {"<replica-1-name>": 60, "<replica-2-name>": 40}
    }
  }'

Add a replica

Use this endpoint to scale out horizontally and assign traffic to the new replica in one request.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  "https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas" \
  -d '{
    "replica_size": "4-16",
    "existing_replicas": {
      "old_weights": {
        "copyjob": {"<replica-1-name>": 1},
        "writer": {"<replica-1-name>": 100},
        "reader": {"<replica-1-name>": 100}
      },
      "new_weights": {
        "copyjob": {"<replica-1-name>": 1},
        "writer": {"<replica-1-name>": 70},
        "reader": {"<replica-1-name>": 80}
      }
    },
    "new_replica": {
      "copyjob": 1,
      "writer": 30,
      "reader": 20
    }
  }'

Remove a replica

Use this endpoint to scale in and move traffic away from the replica being removed.

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  "https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas/<replica_name>" \
  -d '{
    "old_weights": {
      "copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1, "<replica-3-name>": 1},
      "writer": {"<replica-1-name>": 50, "<replica-2-name>": 30, "<replica-3-name>": 20},
      "reader": {"<replica-1-name>": 50, "<replica-2-name>": 30, "<replica-3-name>": 20}
    },
    "new_weights": {
      "copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
      "writer": {"<replica-1-name>": 60, "<replica-2-name>": 40},
      "reader": {"<replica-1-name>": 60, "<replica-2-name>": 40}
    }
  }'

Why this matters

It's an API. You can script it. That means you can wire rebalancing into your runbooks, automate scale-out from your own control plane, or standardize cluster changes across organizations.