# Cluster

> Monitor distributed cluster topology, replication health, and Keeper/ZooKeeper coordination state.

| | |
|---|---|
| **Routes** | `/clusters`, `/keeper/overview`, `/keeper`, `/keeper/info`, `/keeper/connections`, `/keeper/connection-log`, `/keeper/log`, `/keeper/watches` |
| **Feature id** | `cluster` |
| **Default access** | `public` |
| **Requires auth** | No (set `CHM_FEATURE_CLUSTER_ACCESS=authenticated` to gate) |
| **System tables** | `system.clusters`, `system.zookeeper`, `system.zookeeper_info`, `system.zookeeper_connection`, `system.zookeeper_connection_log`, `system.zookeeper_log`, `system.zookeeper_watches` |
| **ClickHouse grants** | `SELECT` on the system tables above |

## What it does

The Cluster section answers two questions: what nodes make up your cluster, and how is Keeper/ZooKeeper coordinating them?

The **Clusters** page renders an interactive topology map of every shard and replica pulled from `system.clusters`. Use it to confirm shard layouts, spot misconfigured hosts, or audit cluster membership after a scaling event.

The **Keeper** sub-section shows the ZooKeeper/ClickHouse Keeper coordination layer: node health, liveness, request latency, the znode tree, active watches, and connection history. These pages are only available when your ClickHouse server has Keeper or ZooKeeper configured.

## Pages

| Page | Route | What it shows | System tables |
|---|---|---|---|
| Clusters | `/clusters` | Interactive topology map, shard/replica membership | `system.clusters` |
| Keeper Overview | `/keeper/overview` | Liveness, request load, latency, per-node cluster state | `system.zookeeper_info` |
| Data Browser | `/keeper?path=/` | Browse the znode tree | `system.zookeeper` |
| Keeper Info | `/keeper/info` | Per-node role, raft log, znode counts, latency | `system.zookeeper_info` |
| Connections | `/keeper/connections` | Live connections from this server to Keeper | `system.zookeeper_connection` |
| Connection Log | `/keeper/connection-log` | History of connect/disconnect events with reasons | `system.zookeeper_connection_log` |
| Request Log | `/keeper/log` | Per-request log of Keeper operations and responses | `system.zookeeper_log` |
| Watches | `/keeper/watches` | Currently active watches registered by this server | `system.zookeeper_watches` |

## Permissions & access

All Cluster pages use the `cluster` feature id.

Disable the entire section:

```bash
CHM_FEATURE_CLUSTER_ENABLED=false
```

Require authentication:

```bash
CHM_FEATURE_CLUSTER_ACCESS=authenticated
```

Using a config file (`CHM_CONFIG_FILE`):

```toml
[features.cluster]
enabled = true
access = "authenticated"
```

## Configuration

No feature-specific configuration. Keeper pages appear automatically when `system.zookeeper_info` is accessible on the connected host. If the table is absent (no Keeper configured), pages show an empty state rather than an error.

## Notes & limitations

- **Keeper tables are optional.** `system.zookeeper`, `system.zookeeper_info`, `system.zookeeper_connection`, `system.zookeeper_connection_log`, `system.zookeeper_log`, and `system.zookeeper_watches` only exist when ClickHouse Keeper or ZooKeeper is configured. Pages backed by missing tables show an informational empty state.
- `system.zookeeper_log` requires `<zookeeper_log>` to be enabled in the ClickHouse server config.
- The topology map requires `system.clusters` and correctly populated `host_name`/`port` values. Clusters defined only in `remote_servers` with unresolvable hostnames still appear but may lack connection metadata.
- The Connections page shows live connections at query time; historical data is in the Connection Log.

## Related

- [Authentication](/authentication)
- [Feature permissions](/advanced/feature-permissions)
- [ClickHouse system.clusters docs](https://clickhouse.com/docs/en/operations/system-tables/clusters)
- [ClickHouse system.zookeeper docs](https://clickhouse.com/docs/en/operations/system-tables/zookeeper)