Skip to main content

Cluster Configuration

YedMQ uses Raft to coordinate distributed state. This page covers the fields that matter when running multiple nodes and how the current REST workflows fit around them.

Example configuration​

[cluster]
cluster_name = "YedMQ"
node_id = 1001
heartbeat_interval = 10
store_dir = "./store"
session_ttl = 86400
startup_mode = "bootstrap"
nodes = [
    { id = 1001, rpc_address = "node1.example.com:3457", api_address = "node1.example.com:3456" },
    { id = 1002, rpc_address = "node2.example.com:3457", api_address = "node2.example.com:3456" },
    { id = 1003, rpc_address = "node3.example.com:3457", api_address = "node3.example.com:3456" },
]

[cluster.rpc]
external = "0.0.0.0:3457"

Main settings​

  • cluster_name: logical name shared by all nodes in the same cluster
  • node_id: unique numeric identifier for the current node
  • heartbeat_interval: Raft heartbeat interval in seconds
  • store_dir: directory used for Raft logs and replicated state
  • session_ttl: disconnected session retention window; set this explicitly for real deployments
  • startup_mode:
    • bootstrap: first-node mode; the raft groups initialize from the configured member list on startup
    • join: scale-out mode; the node waits to be added through cluster management APIs
  • nodes: known node list with each node's rpc_address and api_address
  • cluster.rpc.external: bind address for inter-node RPC traffic

Current replicated state​

YedMQ currently maintains three dedicated raft groups:

  • topic metadata
  • session actor mapping
  • session state

This is why cluster APIs often act on three raft groups at once.

  1. Start the initial node or initial member set with startup_mode = "bootstrap".
  2. Start each new node with startup_mode = "join".
  3. Add the new node through the management API:
    • POST /api/v1/cluster/learners adds a learner to the three raft groups.
    • POST /api/v1/cluster/nodes performs learner addition plus membership change in one request.
  4. Use GET /api/v1/cluster/metrics to confirm the new node has joined cleanly.

Example request for the one-shot add-node workflow:

{
  "node_id": 1002,
  "node": {
    "rpc_addr": "10.0.0.2:3457",
    "api_addr": "10.0.0.2:3456"
  },
  "members": [1001, 1002]
}

Manual initialization endpoints​

Bootstrap mode initializes raft state on startup, but explicit init endpoints also exist for operational workflows:

  • POST /api/v1/cluster/init
  • POST /api/v1/cluster/raft/topic/init
  • POST /api/v1/cluster/raft/session_actor_map/init
  • POST /api/v1/cluster/raft/session_state/init