ClickHouse separates cluster topology (routing) from replication into two independent layers that must stay consistent. The cluster definition in `remote_servers` is purely a routing map used for query distribution and DDL propagation, while actual replication is governed by ZooKeeper/Keeper paths in ReplicatedMergeTree tables. Key guidance includes: using `default_replica_path` with `{uuid}` macros instead of hardcoded table names, always setting `internal_replication = true` with Distributed tables to avoid duplicate writes, keeping cluster configs identical across all nodes to prevent silent topology bugs, and watching for common pitfalls like Keeper path collisions, hostname mismatches, and tables going read-only when Keeper loses connectivity.
Table of contents
How a Node Knows Its Cluster TopologyThe Two Layers: Routing vs. ReplicationWhere the Layers Must AgreeCommon PitfallsKey TakeawaysSort: