ClickHouse (clickhouse)

Column-oriented analytics database for traces, audit events and usage metrics. Single server or sharded and replicated cluster with ClickHouse Keeper.

Generated from catalog/services/clickhouse.yaml: do not edit by hand.

Summary

Version	25.3.3.42
Use	install and configure
Layer	infrastructure (shown apart)
Category	Data platforms
Installation methods	podman, package
External connection	clickhouse
Sandbox only	no

Licence

SPDX identifier	Apache-2.0
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	clickhouse

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	docker.io/clickhouse/clickhouse-server	25.3.3.42	Apache-2.0	image key server, used by keeper, server, digest sha256:cc6b7488017512db99bff97c493030152bb786249afdfec8b6714eaf16a6f4ae
OS package	clickhouse-server	version of the configured repository	Apache-2.0	RHEL family (dnf)
OS package	clickhouse-client	version of the configured repository	Apache-2.0	RHEL family (dnf)
OS package	clickhouse-common-static	version of the configured repository	Apache-2.0	RHEL family (dnf)
OS package	clickhouse-server	version of the configured repository	Apache-2.0	Debian family (apt)
OS package	clickhouse-client	version of the configured repository	Apache-2.0	Debian family (apt)
OS package	clickhouse-common-static	version of the configured repository	Apache-2.0	Debian family (apt)

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
podman	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)
package	RHEL family (dnf), Debian family (apt)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

• at least 4096 MB of memory (blocking, memory).
• at least 2 CPU (warning, cpu).

Network and ports

Component	Port name	Port	Opened in the host firewall
keeper	keeper	9181/tcp	yes
keeper	raft	9234/tcp	yes
server	http	8123/tcp	yes
server	native	9000/tcp	yes
server	interserver	9009/tcp	yes
server	metrics	9363/tcp	yes

Services and connections needed

This service has no dependency.

Installation methods and modes

Method	Default	What the method uses
podman	yes	the container images of the descriptor, run by Podman under systemd
package	-	the OS packages of the descriptor, installed by the package manager of the host

Components

Component	Kind	Installation methods	Ports
ClickHouse Keeper (keeper)	master	podman, package	9181/tcp, 9234/tcp
ClickHouse server (server)	master	podman, package	8123/tcp, 9000/tcp, 9009/tcp, 9363/tcp

Single server (standalone) (default)

One ClickHouse server without Keeper.

What the mode deploys:

Component	Placement
keeper	not used
server	min 1, max 1

Sharded and replicated (cluster)

Shards of replicas (servers count multiple of the replicas) coordinated by 3 or 5 Keeper nodes.

What the mode deploys:

Component	Placement
keeper	min 3, max 5, odd number, recommended 3
server	min 2, recommended 4

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select ClickHouse. The card shows the licence Apache-2.0. Pick the Method among podman, package (default podman). To register an existing clickhouse service of your organisation instead, turn on Use an existing external service.

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), cluster. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).

4. Bindings. This service has no dependency: the Bindings step has nothing to bind.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.

High availability

Cluster	native (native)
High availability	native (native)
Failover	client side (client)
Replication	native (native)
Quorum	ClickHouse Keeper (keeper)
Discovery	static (static)
Entry point	any node (any-node)
Official documentation	https://clickhouse.com/docs/guides/oss/deployment-and-scaling/keeper
Peer TLS parameter	tls_enabled
Cluster status command	system_clusters

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
standalone	standalone (standalone)	single (single)	-	1	One server without Keeper, no replication.
cluster	cluster (cluster)	active-active (active-active)	keeper	3	Shards of 2 or more replicas coordinated by 3 or 5 ClickHouse Keeper nodes.

Notes

• Only Replicated*MergeTree tables are copied between replicas; a plain MergeTree table lives on one server.
• Place the Keeper nodes in distinct fault domains: losing the Keeper majority makes the replicated tables read only.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
HTTP port (http_port)	port	8123	-	no	no	no	Port of the HTTP interface (HTTPS only when TLS is on).
Native port (native_port)	port	9000	-	no	no	no	Port of the native TCP protocol (native protocol over TLS only when TLS is on).
Interserver port (interserver_port)	port	9009	-	no	no	no	Port used by replicas to fetch parts (HTTPS only when TLS is on).
Metrics port (metrics_port)	port	9363	-	no	no	no	Port of the Prometheus endpoint. Unused when TLS is on: /metrics is then served over HTTPS on the HTTP port.

Cluster

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Keeper client port (keeper_port)	port	9181	-	no	no	no	Port of ClickHouse Keeper for the servers (TLS only when TLS is on).
Keeper Raft port (keeper_raft_port)	port	9234	-	no	no	no	Port of the Raft protocol between Keeper nodes (secure Raft when TLS is on).
Cluster name (cluster_name)	string	navin	^[a-z][a-z0-9_]{0,40}$	no	no	no	Name of the cluster in remote_servers (ON CLUSTER).
Replicas per shard (replicas)	int	2	min 1, max 5	no	no	no	Servers per shard; the servers are grouped in topology order.

Tuning

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Memory ratio (max_server_memory_ratio)	float	0.8	min 0.1, max 0.95	no	no	no	Share of the host memory the server may use.

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Administrator password (admin_password)	password	generated	-	no	yes	no	Password of the navin_admin user (access management, operator commands).
Interserver password (interserver_password)	password	generated	-	no	yes	no	Credential shared by the replicas.
TLS (tls_enabled)	bool	false	-	no	no	yes	Serve HTTPS, the native protocol over TLS, interserver HTTPS and, in cluster mode, Keeper and its Raft over TLS with the certificate issued by the manager CA; the plaintext ports are closed.

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
http	http	server	8123 (http_port)	-	tls_enabled	username, database, tls	password	provision_consumer
native	clickhouse	server	9000 (native_port)	-	tls_enabled	username, database, tls	password	provision_consumer

Commands

Command	Component	Target	Description
Provision a consumer database (provision_consumer)	server	first host	Creates or updates the user and the database of one consumer service on the whole cluster (idempotent).
Provision the telemetry database (provision_telemetry)	server	first host	Creates the database navin_manager of the real-time telemetry of the machines and services, its writer navin_manager (NM_CLICKHOUSE_USER of the Manager) and the read only user navin_reader of the SQL analyses and of the dashboards run by the client (idempotent).
Cluster layout (system_clusters)	server	first host	Lists system.clusters (shards, replicas, errors).
Replication queue (replication_queue)	server	every host	Shows the pending replication tasks of every server.

Command parameters

Command	Parameter	Type	Default	Required	Description
provision_consumer	Database (database)	string	-	yes	Database of the consumer.
provision_consumer	User (username)	string	-	yes	User of the consumer.
provision_consumer	Password (password)	password	-	yes	Password of the user (derived per consumer).
provision_telemetry	Writer password (writer_password)	password	-	yes	Password of navin_manager, the user the Manager exports with (NM_CLICKHOUSE_PASSWORD_FILE).
provision_telemetry	Reader password (reader_password)	password	-	yes	Password of navin_reader, read only user of the dashboards (SELECT on navin_manager only).

Health checks

Liveness (per instance)

Component	Check	Details
keeper	TCP {{ host.ip or '127.0.0.1' }}:{{ config.keeper_port }}	-
server	HTTP {{ ('https://' ~ host.fqdn) if config.tls_enabled else ('http://' ~ (host.ip or '127.0.0.1')) }}:{{ config.http_port }}/ping	Expected 200; Expected Ok.; 60 retries

Readiness (service check)

Check	Details
HTTP {{ ('https://' ~ host.fqdn) if config.tls_enabled else ('http://' ~ (host.ip or '127.0.0.1')) }}:{{ config.http_port }}/ping	Expected 200

Preflight checks

Check	Type	Meaning	Severity	Components
memory	memory_mb {"min": 4096}	at least 4096 MB of memory	blocking	every component
cpu	cpu_count {"min": 2}	at least 2 CPU	warning	every component
http_port_free	port_free {"param": "http_port"}	port 8123 free on the host	blocking	server

Backup and restore

Native BACKUP of every non system database to the local disk navin_backups, archived; the restore drops the non system databases and runs RESTORE (P5C-008, engines clickhouse_backup and clickhouse_restore). Mode standalone only: the sharded mode needs BACKUP ON CLUSTER to a shared disk and is refused by the script with an explicit message.

Format	clickhouse-native
Component	server
Files	{{ backup.dir }}/clickhouse.tar.gz
Restore test	no
Instances stopped for the restore	no

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Quick links

• Play (SQL console): {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.http_port }}/play

Upstream documentation

• Homepage: https://clickhouse.com
• Source: https://github.com/ClickHouse/ClickHouse
• High availability: https://clickhouse.com/docs/guides/oss/deployment-and-scaling/keeper