Configuring ClickHouse

Okapi stores telemetry in ClickHouse. Okapi always uses Clickhouse in distributed mode with a densely connected topology.

Okapi treats a distributed CH deployment as being exposed behind a single entry-point. This configuration can be achieved by connecting all Clickhouse replicas with a ClusterIP.

Scope

This guide ClickHouse configuration only. Kubernetes Secret storage and Helm value wiring are documented in the production deployment guide.

Distributed ClickHouse

Okapi’s ops migration Job and ingester need only one ClickHouse Service endpoint. For a distributed ClickHouse installation, expose one or more query-capable ClickHouse nodes behind a Kubernetes ClusterIP Service, for example okapi-clickhouse.

The ops Job connects through this Service and issues schema commands with ON CLUSTER 'okapi'. ClickHouse distributes those commands to the nodes using its configured cluster topology and coordination service. ingester can use the same Service for reads and writes; it does not need pod-specific ClickHouse hostnames.

The Service does not have to select every ClickHouse node. It must route to at least one healthy node that knows the complete cluster topology and can execute distributed queries and DDL.

Cluster requirements

The ClickHouse cluster must satisfy these requirements:

The cluster is named exactly okapi; Okapi migrations use ON CLUSTER 'okapi'.
Every node has a compatible remote_servers definition for the okapi cluster and the correct shard and replica macros.
ClickHouse Keeper or ZooKeeper is configured for the ReplicatedMergeTree tables created by Okapi.
Distributed DDL is configured and operational on every node.

ClickHouse user

One ClickHouse account shared by ops and ingester is sufficient. If you prefer least-privilege separation, configure distinct migration and runtime accounts and give each chart its own Secret.

Account	Used by	Required access
migration	`ops`	Create the `okapi_metrics`, `okapi_traces`, and `okapi_logs` databases and their tables; execute this DDL with `ON CLUSTER`
runtime	`ingester`	`SELECT` and `INSERT` on the three Okapi databases

When one account is shared, it needs the union of these permissions. The configured account must exist with equivalent grants on every node that can receive an ON CLUSTER task or a client connection.

Admins note

DO NOT expose individual ClickHouse pod addresses to the Okapi charts. The only endpoint they need is the common Service DNS name and HTTP port, for example:

clickhouse:
  host: okapi-clickhouse
  port: 8123

Configuring PostgreSQL Getting started locally