ClickHouse

The ClickHouse Helm chart provides an easy way to deploy and manage a ClickHouse OLAP database in your Kubernetes environment. This chart includes configurations for persistence, resource management, built-in Prometheus metrics, and automatic provisioning of application databases and users.

Prerequisites

• Kubernetes 1.19+
• Helm 3+
• Stakater Reloader (optional, recommended) — required only for the pod to restart automatically when customConfig changes. See Config changes and automatic restarts.

Add Helm Repository

Before installing the ClickHouse chart, add the repository to your Helm installation and update the repository index:

helm repo add zopdev https://helm.zop.dev
helm repo update

See Helm Repository Documentation for more details.

Install Helm Chart

To install the ClickHouse Helm chart, run the following command:

helm install [RELEASE_NAME] zopdev/clickhouse

Replace [RELEASE_NAME] with your desired release name.

For example:

helm install my-clickhouse zopdev/clickhouse

You can customize the installation by providing a custom values.yaml file or overriding values via the command line.

See Helm Install Documentation for further details.

Uninstall Helm Chart

To uninstall the ClickHouse Helm chart and remove all associated Kubernetes resources, run:

helm uninstall [RELEASE_NAME]

For example:

helm uninstall my-clickhouse

See Helm Uninstall Documentation for more information.

Configuration

The following table describes the configurable parameters of the ClickHouse Helm chart and their default values:

You can override these values in your values.yaml file or pass them as flags when installing the chart.

Example values.yaml File

diskSize: "10Gi"

resources:
  requests:
    cpu: "500m"
    memory: "512M"
  limits:
    cpu: "2000m"
    memory: "2048M"

version: "25.3"

customConfig: ""

services:
  - name: orders
    database: analytics

To use this configuration, save it in a values.yaml file and pass it to the Helm install command:

helm install my-clickhouse zopdev/clickhouse -f values.yaml

Example: Providing Custom ClickHouse Configuration

To override or add to the default ClickHouse configuration, provide your own XML using the customConfig value. The same document is mounted into both ClickHouse config trees:

• /etc/clickhouse-server/config.d/custom.xml — for server-level settings (e.g. max_connections, max_server_memory_usage_to_ram_ratio).
• /etc/clickhouse-server/users.d/custom.xml — for profile / user settings, which ClickHouse only loads from the users config tree (e.g. max_memory_usage, max_bytes_before_external_group_by, max_bytes_before_external_sort).

ClickHouse reads the relevant sections from each tree and ignores the rest, so you can place server settings and a <profiles> block in one document:

customConfig: |
  <clickhouse>
    <max_connections>2048</max_connections>
    <max_concurrent_queries>200</max_concurrent_queries>
    <max_server_memory_usage_to_ram_ratio>0.9</max_server_memory_usage_to_ram_ratio>
    <profiles>
      <default>
        <max_memory_usage>1500000000</max_memory_usage>
        <max_bytes_before_external_group_by>750000000</max_bytes_before_external_group_by>
        <max_bytes_before_external_sort>750000000</max_bytes_before_external_sort>
      </default>
    </profiles>
  </clickhouse>

Config changes and automatic restarts

customConfig (and the bundled Prometheus config) is mounted using subPath. Kubernetes never live-updates subPath mounts, so a helm upgrade that changes customConfig updates the ConfigMap but the running pod keeps the old file until it restarts.

The StatefulSet is annotated for Stakater Reloader. The -clickhouse-prometheus ConfigMap is always watched; -clickhouse-custom-config is added to the list only when customConfig is set (it isn’t created otherwise):

# customConfig set:
configmap.reloader.stakater.com/reload: "<release>-clickhouse-prometheus,<release>-clickhouse-custom-config"
# customConfig unset:
configmap.reloader.stakater.com/reload: "<release>-clickhouse-prometheus"

If the Reloader controller is running in the cluster, it detects the ConfigMap change and triggers a rolling restart automatically. If Reloader is not installed, the annotation is a no-op — the config change silently won’t take effect until you restart the pod yourself:

kubectl rollout restart statefulset/<release>-clickhouse

Provisioning Databases and Users

Use the services array to provision one database and user per application. For each entry the chart creates:

• the database (CREATE DATABASE IF NOT EXISTS),
• a dedicated user with SELECT, INSERT, ALTER, CREATE, DROP, TRUNCATE, OPTIMIZE on that database,
• a ConfigMap (<release>-<database>-<name>-clickhouse-configmap) with the connection details, and
• a Secret (<release>-<database>-<name>-clickhouse-database-secret) holding the user’s password.

A short-lived init Pod (clickhouse-init-<release>-<name>) applies the SQL via clickhouse-client. Generated credentials are preserved across upgrades by reading back the existing secret.

Ports

Features

• Persistence: Data is stored on a persistent volume claim, surviving pod restarts.
• Customizable Resources: Define resource requests and limits to optimize performance and manage costs.
• Built-in Metrics: ClickHouse’s native Prometheus exporter is enabled on port 9363; a ServiceMonitor and PrometheusRule are bundled.
• Automatic Provisioning: Declaratively create databases and users via the services value.
• Health Probes: Liveness and readiness probes use the /ping HTTP endpoint.

Monitoring

The chart enables ClickHouse’s built-in Prometheus endpoint (no sidecar exporter required) and ships:

• a ServiceMonitor scraping the metrics-port (/metrics, 30s interval), and
• a PrometheusRule with alerts for instance down, recent restart, rejected inserts, and excessive connections.

Pod Scheduling

nodeSelector, tolerations and affinity are passed straight through to the pod spec. All three are empty by default and render nothing, so leaving them unset changes nothing for an existing release.

Together they place the workload on a dedicated node pool — the nodeSelector picks the pool, the toleration gets past its taint:

nodeSelector:
  workload: stateful

tolerations:
  - key: workload
    operator: Equal
    value: stateful
    effect: NoSchedule

affinity takes a full Affinity object and is rendered verbatim.

Contributing

We welcome contributions to improve this Helm chart. Please refer to the CONTRIBUTING.md file for guidelines.

Code of Conduct

To ensure a respectful and collaborative community, please adhere to our Code of Conduct.

License

This project is licensed under the LICENSE. Please review it for terms of use.

Connection Config

The connection ConfigMap/Secret expose CH_* keys (the consumer combines CH_HOST:CH_PORT into GoFr’s ClickHouse Hosts, see gofr.dev/docs/datasources/clickhouse):

• CH_HOST : Hostname/service name of the ClickHouse server (<release>-clickhouse).
• CH_PORT : Native TCP port. Defaults to 9000. (HTTP clients use 8123.)
• CH_USER : Username used to connect to the ClickHouse database.
• CH_DATABASE : The name of the specific database to connect to.
• CH_PASSWORD : The password for CH_USER, stored securely in a Kubernetes secret.