Configure a replicated cluster
This page builds a 2 shard x 2 replica cluster of Alauda Data Services Analytical Database E1 and creates a replicated table on it.
TOC
What replication requiresThe instanceConfirm the cluster and the quorumMacrosCreate a replicated tableON CLUSTER needs the coordination elementSchema propagation when you add hostsScalingVerify replication is healthyWhat replication requires
Replication and cluster-wide DDL both need a ZooKeeper-compatible coordination quorum. The instance can get one in two ways:
- A
ClickHouseKeeperInstallation(recommended). The operator deploys and manages a ClickHouse Keeper quorum from the server image this product already ships, and the instance refers to it by name underzookeeper.keeper. The operator resolves the name to the members' addresses. If you do not have one yet, Deploy a Keeper quorum creates a three-member quorum namedkeeper, which the manifest below uses. - A quorum you run yourself. Any ZooKeeper-compatible ensemble, including a Keeper StatefulSet you built by hand with an earlier release of this guide, keeps working. List its members under
zookeeper.nodesinstead, onehostentry per member.
Use one or the other in a given zookeeper block, not both: the operator adds the members it resolves from keeper to whatever nodes already lists.
The instance
Notes:
portunder each node defaults to 2181, so you only needhostfor a standard quorum.shardsCount: 2withreplicasCount: 2is four hosts. Each host is its own StatefulSet with one pod, so you get four pods and four data volumes.- The quorum may live in another namespace;
keeper.namespacenames it. Leavenamespaceout when the quorum is in the instance's own namespace. If the quorum is not ready yet, the instance waits for it. - A cluster can override the instance-wide quorum with its own
zookeeperblock, which is how two clusters in one instance can use separate quorums.
Apply it and wait for all four hosts:
Confirm the cluster and the quorum
Four rows, two shards, two replicas each.
Then confirm the server can actually reach the quorum:
If that query fails, stop here and fix coordination before creating any replicated table. See ON CLUSTER DDL fails with NO_ELEMENTS_IN_CONFIG.
Macros
The operator writes per-host macros into each host's configuration, so table definitions can be written once and applied to every host:
Use them in replication paths rather than hard-coding host names.
Create a replicated table
The two ReplicatedMergeTree arguments are the coordination path and the replica identity. Both replicas of a shard must share the path and differ in identity, which the macros guarantee.
To query across shards, add a Distributed table over the same schema:
Write to analytics.events on a shard, or to analytics.events_all to distribute writes.
ON CLUSTER needs the coordination element
ON CLUSTER is not a client-side convenience. The server broadcasts the statement through the coordination quorum, so it requires the quorum element to be present in the server configuration.
The operator only emits that element when the instance declares coordination, either as zookeeper.keeper or as zookeeper.nodes. An instance with neither gets no coordination element at all, and then every ON CLUSTER statement fails with NO_ELEMENTS_IN_CONFIG — even though distributed DDL itself is enabled in the stock server configuration. The missing piece is always the coordination element.
If you cannot use ON CLUSTER, run the CREATE statement on each host individually. Prefer ON CLUSTER once coordination is in place.
Schema propagation when you add hosts
When you grow the topology, the operator propagates existing schema to new hosts during reconcile. It reads the object definitions from the hosts that already have them, rewrites each CREATE into a CREATE ... IF NOT EXISTS, and executes it on the new host. Replicated objects and views are what it propagates; it needs at least two hosts in a shard before there is anything to copy.
This behaviour is governed by schemaPolicy:
replica accepts None or All. shard accepts None, All or DistributedTablesOnly. Both default to All. Set replica: None to take over schema management yourself.
Scaling
Raise replicasCount to add a replica to every shard, or shardsCount to add shards. The operator reconciles hosts one at a time: it excludes a host from the cluster, applies changes, waits for it to be ready, then includes it again. Adding a shard does not redistribute existing data; plan that separately.
Verify replication is healthy
is_readonly = 1 means the replica has lost coordination. A growing queue_size or absolute_delay means a replica is falling behind. Both are worth alerting on — see Monitoring.
ClickHouse is a registered trademark of ClickHouse, Inc. https://clickhouse.com
Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by ClickHouse, Inc. All trademarks are the property of their respective owners and are used here for identification purposes only.