Clustering

Run Argyll nodes under Raft consensus and route traffic to the leader.

Raft Nodes

Argyll uses Raft for consensus. Run at least 3 nodes for high availability. Each node reads its identity and cluster membership from the RAFT_* environment variables.

Single Node (development)

RAFT_NODE_ID=argyll-1
RAFT_ADDRESS=127.0.0.1:9701
RAFT_DATA_DIR=/tmp/argyll-raft/argyll-1
RAFT_SERVERS=argyll-1=127.0.0.1:9701

Three-Node Cluster

# On each node, set its own RAFT_NODE_ID and RAFT_ADDRESS,
# but the same RAFT_SERVERS listing all nodes:
RAFT_NODE_ID=argyll-1
RAFT_ADDRESS=argyll-1:9701
RAFT_DATA_DIR=/var/lib/argyll/raft/argyll-1
RAFT_SERVERS=argyll-1=argyll-1:9701,argyll-2=argyll-2:9702,argyll-3=argyll-3:9703

A write is committed only after enough voting nodes accept it. Any node can serve reads. Clients send writes to the leader, and nodes forward their own internal writes to the leader as needed.

Health Check

GET /health

Returns 200. The response header X-Argyll-Raft-State contains the node’s role: leader, candidate, follower, or unknown. Use this for load balancer routing.

HAProxy Leader-Aware Routing

Route write traffic only to the Raft leader:

backend argyll_write
  option httpchk GET /health
  http-check expect hdr name "X-Argyll-Raft-State" value -m str leader
  server n1 argyll-1:8080 check
  server n2 argyll-2:8080 check
  server n3 argyll-3:8080 check

backend argyll_read
  option httpchk GET /health
  http-check expect status 200
  server n1 argyll-1:8080 check
  server n2 argyll-2:8080 check
  server n3 argyll-3:8080 check

Write paths: mutating /engine/steps and /engine/spaces requests, POST /engine/flows, and POST /callbacks/*. Read-style POSTs like POST /engine/plan, POST /engine/spaces/preview, and POST /engine/flows/query can go to any node.