Cluster Expansion & Final Checks

Adding a replica to an existing shard #

Follow the same steps. Assign the new node the existing shard ID and a new replica ID, then update cluster.xml on every node.

For example, adding Replica 02 to Shard 01:

Shard 01:
  shard1-node.example.com        (replica 01)
  shard1-replica2.example.com    (replica 02)

Shard 02:
  shard2-node.example.com        (replica 01)

The new replica uses shard=01 and replica=02 in macros.xml. Add a second <replica> entry inside the first <shard> in the shared cluster.xml:

<replica>
    <host>shard1-replica2.example.com</host>
    <port>9000</port>
</replica>

Ensure hostname resolution, Keeper access, trusted-network permissions, and matching ClickHouse versions. Apply the configuration once, run nfaadm --init ts from the NFA node, and allow time for synchronization.

Completion checklist #

• ☐ Matching ClickHouse 26.3.x versions on all nodes
• ☐ Hostname resolution and TCP 9000 / 9181 connectivity
• ☐ Correct macros and identical cluster.xml on all nodes
• ☐ Trusted inter-node access and distributed query setting
• ☐ Cluster query returns every configured node
• ☐ nfaadm --init ts completed on the NFA node
• ☐ NFA database present on all nodes; replicas active
• ☐ NFA services restarted

Note: Adding a shard does not automatically rebalance historical data. Adding a replica synchronizes data for its existing shard.