Install ClickHouse
System Requirements and Runtime Notes
ClickHouse is configured to run with a minimum of 16 GB RAM. You can further optimize performance by applying the best practices for schema design, memory management, and storage.
The 3.3.6 ODP distribution includes JDK 11 and Python 3 as standard runtime components.
Steps to Install
- Run the following command to install Mpack on Ambari Server.
ambari-server install-mpack --mpack=ambari-mpacks-clickhouse-25.x.tar.gz --verbose- To begin, add the ClickHouse service from the list in the Ambari UI. Once added, proceed with the installation steps.
- Choose your deployment template based on your specific requirements. Here are some reusable examples, but note that actual deployment may vary depending on your use case:
| Server | Keeper | Web Server | Keeper Node List* | Shard | Replica | Host Shard Replica Map** |
|---|---|---|---|---|---|---|
| 1 | 1 | 1 | 1 | 1 | 1 | hostA:1:1 |
| 3 | 3 | 3 | 1@hostA,2@hostB,3@hostC | 1 | 3 | hostA:1:1,hostB:1:2,hostC:1:3 |
| 6 | 3 or 6 | 3 | 1@hostA,2@hostB,3@hostC | 3 | 2 | hostA:1:1,hostB:1:2,hostC:2:1,hostD:2:2,hostE:3:1,hostF:3:2 |
- Set the Cluster Name and Cluster Secret values.
- Configure the Keeper Node List using the format shown in the templates above.
- Define the Host-Shard-Replica Mapping as per the template examples provided.
Once these settings are configured, proceed to the next steps to deploy the service.
Ideal case for HA: ClickHouse Cluster requirements: Minimum 2 servers + 3 Keepers for quorum
Keeper Management
The Keeper Node List configuration manages the persistent mapping of Node IDs to hostnames. Currently, this mapping must be manually specified by the user and set within the configuration files under the keeper_config.d directory on each host.
Important Requirements:
- Follow the right syntax as mentioned in the example: ID@FQDN → 1@host1.acceldata.ce
- Do not assign the same Node ID to multiple hosts. Each host must have a unique Node ID.
- Avoid reusing old Node IDs when replacing or adding new hosts. This helps prevent conflicts and data corruption.
- Always assign a new, incremented Node ID when provisioning a new or replacement host.
For additional information, see the Keeper Maintenance section below.
Keeper Maintenance
Adding a Keeper Node To add a Keeper node, update the Keeper Node List configuration, ensuring that the Keeper management rules are followed. After making the changes, perform a rolling restart of the Keeper service.
Removing a Keeper Node To remove a Keeper node, modify the Keeper Node List configuration while following the Keeper management rules. After the update, perform a rolling restart of the Keeper service.
Shard Replica Management
The Host Shard Replica Map configuration in Ambari defines and persists the cluster topology across hosts. It informs each node about the overall cluster structure, including the number of shards and replicas.
The configuration follows this format:
<hostFQDN>:<shard_id>:<replica_id>Example: For a 3-node cluster with 1 shard and 3 replicas, the Host Shard Replica Map configuration looks like:
hostA:1:1,hostB:1:2,hostC:1:3- hostA, hostB, and hostC are the fully qualified domain names (FQDNs) of the ClickHouse servers.
- The second value (1) is the shard ID (same for all, since there’s only 1 shard).
- The third value (1, 2, 3) is the replica ID.
The above configuration represents 1 shard with 3 replicas, and each node contains a replica of the same shard.
Best Practices
The total number of unique ClickHouse server nodes in the cluster must equal the product of shards and replicas, as each (shard, replica) pair maps to one physical node.
Ensure that all nodes use a consistent configuration during the initial cluster setup to avoid mismatches and connectivity issues.
Valid Combinations for a Three-Node Cluster
| Shards | Replicas | Description | Total Server Nodes Required |
|---|---|---|---|
| 1 | 3 | 1 shard replicated across 3 nodes | 3 |
| 3 | 1 | 3 shards, no replication | 3 |
| 1 | 2 | Only 2 nodes needed (not HA on 3) | ❌ Applicable but not recommended |
| 2 | 2 | Requires 4 nodes (not valid here) | ❌ Not applicable |
Server Maintenance
Adding Servers To add a server, update the Host Shard Replica Map configuration as needed for shard–replica management. Ensure all shard management rules are followed. After making the changes, perform a rolling restart of the Servers service.
Removing Servers To remove a server, update the Host Shard Replica Map configuration accordingly. Ensure all shard management rules are followed. After making the changes, perform a rolling restart of the Servers service.
Note: High availability (HA) is not supported for the ClickHouse UI.
Unistall ClickHouse
You can use the following command to uninstall ClickHouse.
ambari-server uninstall-mpack --mpack-name=clickhouse-25.x-mpack --verbose