Build and expand an X2 cluster

Install every node identically, give it unique addresses and storage paths, then join it through the existing cluster. Membership persists in consensus; static seed lists are not the cluster database.

Command platform

Linux

Topology

Choose quorum before adding capacity

All nodes run the complete X2 code. Consensus voting and write eligibility are separate from component availability.

1 node1 voter

Evaluation and small isolated deployments.

2 nodes2 voters

Both must be available for quorum-backed changes.

3–4 nodes3 voters

Recommended starting topology for production.

5+ nodes5 voters

Additional nodes join as non-voters and promote after catch-up.

Prepare unique node identity and networking

Unique node ID and runtime root
Unique public listener and public URL
Unique internal listen and advertised address
TCP 9443 reachable between every X2 node
Clock synchronization and stable DNS
Empty node-local metadata and data roots

Same-machine development: every process needs different public and internal ports plus distinct state, metadata, log, and disk paths.

Install the same release on the new host

Use the installation guide through artifact verification and service installation. Do not bootstrap a second independent cluster. If encryption is enabled, provision a separate KMS workload identity for this node before joining.

Download and verify Create KMS identity

Join through an existing healthy node

Replace <EXISTING_NODE_PUBLIC_DNS_OR_IP> with the DNS name or IP address of a reachable healthy X2 node. Do not copy an example node address into production.

sudo /usr/lib/x2/x2-node join \
  --config /etc/x2/node.yaml \
  --cluster-url https://<EXISTING_NODE_PUBLIC_DNS_OR_IP>:8443 \
  --token '<SINGLE_USE_ENROLLMENT_TOKEN>'

& 'C:\Program Files\X2\x2-node.exe' join `
  --config 'C:\ProgramData\X2\config\node.yaml' `
  --cluster-url 'https://<EXISTING_NODE_PUBLIC_DNS_OR_IP>:8443' `
  --token '<SINGLE_USE_ENROLLMENT_TOKEN>'

sudo /usr/local/lib/x2/x2-node join \
  --config /usr/local/etc/x2/node.yaml \
  --cluster-url https://<EXISTING_NODE_PUBLIC_DNS_OR_IP>:8443 \
  --token '<SINGLE_USE_ENROLLMENT_TOKEN>'

Enrollment tokens must be short-lived and single-use. The joining node starts as a non-voter and cannot write until required consensus state is applied.

Wait for catch-up and promotion

Confirm the node appears in Control with the expected identity and version.
Wait for consensus applied-index convergence.
Register metadata and disk roots.
Confirm placement advertises the expected capacity.
Promote only when the voter policy requires it.
Enable metadata writes before object writes.

Do not bypass fencing: a restarting or newly joined node must reject stale placement generations and writes until convergence is complete.

Validate the expanded cluster

MembershipExpected voters, no duplicate node IDs, one healthy leader.

StorageCorrect disks, metadata roots, capacity, and write policies.

Data pathCreate, list, read, and delete a test object through another node.

FailureStop one voter and verify quorum behavior before admitting traffic.

Node admitted

Proceed only when versions, health, capacity, quorum, and convergence are all correct.

Operate the cluster →