ClickHouse Configuration

ChartVersion3.0.1TypeapplicationAppVersion25.8.11.66

CompatibilityKubernetes1.32+OpenShift4.19+Rancher2.10.x+

Feature SupportLDAPsupportedS3supportedIngresssupportedGateway APIsupported

The tdp-clickhouse chart packages ClickHouse 25.8.11.66 for Kubernetes, using the Altinity ClickHouse Operator (ClickHouseInstallation).

This page focuses on the base configuration of the component: installation, main parameters, persistence, resources and a high availability scenario as a starting example.

For installers and operators, the typical flow is: ensure adequate StorageClass and resource limits, apply the chart with base values, validate ClickHouseInstallation (CHI) and Services, and only then move on to HA, LDAP or S3 integration when the environment requires it.

For security and integration details, see Security — ClickHouse and Integrations — ClickHouse.

What is ClickHouse?

ClickHouse is a high-performance columnar database aimed at analytics.

Instead of storing data row by row, it stores it column by column. This favors fast readings in aggregation scenarios, reports and analytical queries on large volumes of data.

In TDP Kubernetes, ClickHouse is typically used as a destination for already processed data, which is then queried by tools such as Superset, CloudBeaver and Trino.

To find out more

See ClickHouse — Concepts for a complete overview of the tool, its architecture and operation.

How ClickHouse operates on Kubernetes

In TDP Kubernetes, ClickHouse is deployed with the Altinity ClickHouse Operator, in the same declarative spirit as other operators on the platform (by analogy to Kafka with Strimzi): instead of manually creating Pods and Services, you declare the desired state in a ClickHouseInstallation (CHI) resource, and the operator reconciles that state with the cluster.

In practice, in the release namespace, typical elements are:

Component	Description
Altinity Operator	Manages the ClickHouseInstallation lifecycle
ClickHouseInstallation	Resource that defines shards, replicas, storage and cluster configuration
ClickHouse Pods	Data pods created from CHI
Services	ClickHouse access endpoints
PVCs	Persistent volumes for data
Optional Jobs	Auxiliary resources for TDP user, S3 and cleanup

Values structure (Helm)

The tdp-clickhouse chart organizes configuration in the blocks below:

• tdp-clickhouse: — main component configuration, including clickhouse.*, operator.*, keeper.* and cleanup.*.
• TDP-Settings: — optional TDP settings for S3 integration and exposure control through Ingress or Gateway API.
• ingress: and gatewayApi: — parameters used when external exposure is enabled.

tdp-clickhouse:
  clickhouse:
    enabled: true
  operator:
    enabled: true
  cleanup:
    enabled: true

TDP-Settings:
  s3Connection:
    enabled: false
  gateway:
    ingress:
      enabled: false
    gatewayApi:
      enabled: false

ingress:
  hosts:
    - host: clickhouse.tdp.local

gatewayApi:
  clickhouse:
    enabled: true

Overview

Property	Value
Chart	tdp-clickhouse
ClickHouse version	25.8.11.66
Chart version	3.0.1
Operator	Altinity ClickHouse Operator
Main resource	ClickHouseInstallation
Persistence	PVCs for ClickHouse data and, in HA, for ClickHouse Keeper
HTTP exposure	Internal Service, Ingress, or Gateway API for the HTTP interface

Related Pages

• Integrations — ClickHouse — S3/Ozone, TDP users, and consumption integrations
• Security — ClickHouse — LDAP, Secrets, TLS, and permissions
• External exposure: Ingress and Gateway API — HTTP/HTTPS interface exposure

Prerequisites

• Kubernetes 1.32+, Red Hat OpenShift 4.19+ or Rancher Manager 2.10.x+.
• Helm 3.2.0+.
• Default StorageClass on the cluster or tdp-clickhouse.clickhouse.persistence.storageClass explicitly defined.

Installation

Installation (OCI)

helm upgrade --install is idempotent: on the first execution it creates the release; in the following cases, only the value diff is applied. Always use the indicated production registry and a versioned values file (without clear text credentials) to reproduce the same behavior between environments.

Use the production registry:

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
  -n <NAMESPACE> --create-namespace

Main parameters

Main parameters

Parameter	Description	Standard (reference)
tdp-clickhouse.clickhouse.enabled	Enable cluster	true
tdp-clickhouse.clickhouse.image.repository	ClickHouse image repository	clickhouse/clickhouse-server
tdp-clickhouse.clickhouse.image.tag	ClickHouse image tag	25.8.11.66
tdp-clickhouse.clickhouse.persistence.*	PVC: size, storageClass and accessModes	run helm show values
tdp-clickhouse.clickhouse.resources	CPU/memory requests and limits	run helm show values
tdp-clickhouse.clickhouse.defaultUser.password	User password default	""
tdp-clickhouse.clickhouse.extraUsers	Additional profiles and users via XML	run helm show values
tdp-clickhouse.clickhouse.tdpUser.enabled	TDP user with grants job	false
tdp-clickhouse.clickhouse.tdpUser.password	TDP user password (set via private values override when necessary)	""
tdp-clickhouse.operator.enabled	Enable Altinity Operator	true
tdp-clickhouse.cleanup.enabled	Enable pre-delete cleanup job	true
TDP-Settings.s3Connection.enabled	Enable S3 bucket creation job and Secret	false
TDP-Settings.s3Connection.bucket	S3 bucket name	""
TDP-Settings.s3Connection.accessKey	S3 access key	""
TDP-Settings.s3Connection.secretKey	S3 secret key	""
TDP-Settings.s3Connection.uri	S3 endpoint URI	""
TDP-Settings.s3Connection.selfSigned	Skip TLS verification for self-signed endpoints	false

Configuration details

Common labels

tdp-clickhouse.commonLabels allows you to apply additional labels to resources created by the chart. It is useful when the cluster uses its own inventory, observability, or governance conventions.

Operator

The tdp-clickhouse.operator.enabled parameter controls the installation of Altinity Operator as a chart dependency. In most environments, the default of true is sufficient.

Disabling the operator only makes sense when you already have an Altinity installation on your chart-compatible cluster and want to reuse it — otherwise the CHI will not be reconciled and the ClickHouse pods will not appear as expected. When in doubt, keep true and treat the operator as an implicit prerequisite of the TDP stack.

Logging

The chart overrides the ClickHouse logging configuration file via tdp-clickhouse.operator.configs.configdFiles.01-clickhouse-02-logger.xml.

Log level

Always use <level>information</level> — not <level>info</level>. The value info is not recognized by ClickHouse/Poco and may cause unexpected logging behavior.

ClickHouse: persistence and resources

The parameters below are usually the first ones adjusted by whoever installs the component:

Persistence in PVC means that data and state survive pod restart; without it (or undersized), you risk running out of space, disk throttling, or losing data on rebuilds. Requests and CPU/memory limits define how much the scheduler reserves and how far the pod can grow: low values save cluster but can cause OOM or slow queries under load — align with the data volume and query pattern (analytics usually require more memory).

tdp-clickhouse:
  clickhouse:
    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""
      accessModes: ["ReadWriteOnce"]

    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

Attention

Use the prefix tdp-clickhouse.clickhouse.resources and tdp-clickhouse.clickhouse.persistence. Do not use tdp-clickhouse.resources alone.

Portworx StorageClass

When the cluster uses Portworx for database volumes, set tdp-clickhouse.clickhouse.persistence.storageClass and the volume annotations according to the cluster's operational standard:

tdp-clickhouse:
  clickhouse:
    persistence:
      enabled: true
      size: 10Gi
      storageClass: "px-db"
      accessModes: ["ReadWriteOnce"]
      annotations:
        portworx.io/repl: "3"
        portworx.io/io_priority: "high"
        portworx.io/snapshot: "true"
        portworx.io/block_size: "64"

Optional TDP User

When tdp-clickhouse.clickhouse.tdpUser.enabled: true, the chart creates a Secret (tdp-clickhouse-tdp-user) and runs a post-install/post-upgrade Job to apply grants.

This is useful when you want to avoid using the default user by TDP ecosystem applications.

The default user continues to exist for legacy or administrative scenarios; enabling the TDP user centralizes permissions and naming convention for tools that connect to ClickHouse in TDP (for example Superset or CloudBeaver when configured for tdpuser), reducing the need to share the default administrative account.

High Availability (HA)

The chart supports ClickHouse clusters with multiple shards and replicas managed by ClickHouse Keeper.

The reference topology presented below is a starting example for HA environments: 2 shards × 2 replicas = 4 data pods.

Starting example

The HA example on this page is not required and should not be blindly copied to all environments. Use it as a basis to adapt resources, storage, topology and access policies to your reality.

When adapting the example, jointly adjust shards, replicas, PVC size per pod, and antiAffinity (whether there are enough nodes to scatter).

Key concepts

Concept	What does it do	When to use
Shard	Splits data horizontally between nodes	When a single node is no longer sufficient for the data volume
Replica	Maintains an identical copy of the shard	When fault tolerance and read continuity are needed
ClickHouse Keeper	Coordinates replication between pods	Mandatory when replicasCount > 1

Tables must be Replicated

To take advantage of replication, tables need to be created with the ReplicatedMergeTree engine or equivalent variant. Simple MergeTree tables are not automatically replicated.

2×2 Topology (4 pods)

Shard 1 ──┬── Replica 1  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-0-0)
           └── Replica 2  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-0-1)

Shard 2 ──┬── Replica 1  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-1-0)
           └── Replica 2  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-1-1)

ClickHouse Keeper ── (pod: tdp-clickhouse-keeper-0)

Each replica pair synchronizes data via Keeper. The loss of a pod does not interrupt access to the corresponding shard, as long as the table is configured with a replicated engine.

Example of values-ha.yaml

Create a separate file for HA, for example values-ha.yaml, so as not to mix this scenario with the component's base values.

1. Cluster topology and resources

tdp-clickhouse:
  clickhouse:
    antiAffinity: false   # set to true if there are enough nodes
    shardsCount: 2
    replicasCount: 2

    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""
      accessModes: ["ReadWriteOnce"]

    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

2. ClickHouse cluster configuration

    configuration:
      clusters:
        - name: tdp-clickhouse
          layout:
            shardsCount: 2
            replicasCount: 2

      settings:
        distributed_ddl:
          enable: true

      macros:
        cluster: tdp-clickhouse
        shard: '{shard}'
        replica: '{replica}'

3. ClickHouse Keeper

  keeper:
  enabled: true
  replicaCount: 1   # use odd number: 1 or 3

  image: registry.tecnisys.com.br/community/images/clickhouse/clickhouse-keeper
  tag: "25.8.11.66"

  localStorage:
    size: 5Gi
    storageClass: ""

For default user password configuration, LDAP access control and credentials best practices, see Security — ClickHouse.

Apply HA configuration

Terminal input

helm upgrade --install <RELEASE_NAME> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
  -n <NAMESPACE> \
  -f values-ha.yaml

Verification after deployment

After deployment, the ClickHouse pods, the chi resource and, if activated, the Keeper pod should appear:

Terminal input

kubectl -n <NAMESPACE> get pods
kubectl -n <NAMESPACE> get chi

Verify that ClickHouse recognizes the cluster and all nodes:

Terminal input

POD=$(kubectl -n <NAMESPACE> get pods \
  -l clickhouse.altinity.com/chi=<RELEASE_NAME> \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n <NAMESPACE> exec -it "$POD" -- \
  clickhouse-client -q "SELECT cluster, shard_num, replica_num, host_name FROM system.clusters"

The expected output should list the hosts in the configured cluster. In the 2×2 example, there will be 4 hosts.

Main HA parameters

Parameter	Description	Standard
tdp-clickhouse.clickhouse.shardsCount	Number of shards	1
tdp-clickhouse.clickhouse.replicasCount	Replicas per shard	1
tdp-clickhouse.clickhouse.antiAffinity	Distribute pods across different physical nodes	false
tdp-clickhouse.keeper.enabled	Activate ClickHouse Keeper	false
tdp-clickhouse.keeper.replicaCount	Number of Keeper pods	1
tdp-clickhouse.keeper.image	Keeper image	registry.tecnisys.com.br/community/images/clickhouse/clickhouse-keeper
tdp-clickhouse.keeper.localStorage.size	Keeper storage	5Gi

Integrations

For S3 bucket, connection secret, S3 storage policy and consumption by other TDP tools, see Integrations — ClickHouse.

Access & Security

Security

For LDAP authentication, password management, default user access control and additional profiles, see Security — ClickHouse.

External exposure (Ingress and Gateway API)

Required configuration before exposing ClickHouse externally

By default, ClickHouse only accepts connections from 127.0.0.1/::1. Requests from an Ingress controller or Gateway are rejected with AUTHENTICATION_FAILED.

Before enabling Ingress or Gateway API, make sure to include extraUsers with open network permissions — full examples are in External Exposure: Ingress and Gateway API.

For detailed Ingress and Gateway API configuration, see External Exposure: Ingress and Gateway API.

Access

Port-forward (HTTP)

Terminal input

kubectl -n <NAMESPACE> port-forward svc/clickhouse-<RELEASE_NAME> 8123:8123
curl "http://localhost:8123/?query=SELECT%201"

clickhouse-<RELEASE_NAME> is the ClickHouse HTTP Service. Confirm with kubectl get svc -n <NAMESPACE>.

Troubleshooting

Troubleshooting

Terminal input

kubectl -n <NAMESPACE> get pods
kubectl -n <NAMESPACE> get chi
kubectl -n <NAMESPACE> logs deployment/<DEPLOYMENT_NAME>
kubectl -n <NAMESPACE> logs -l clickhouse.altinity.com/chi=<RELEASE_NAME>

Uninstallation

Uninstallation

Terminal input

helm -n <NAMESPACE> uninstall <RELEASE_NAME>

Pre-delete cleanup

When tdp-clickhouse.cleanup.enabled: true, the chart enables a cleanup Job that runs before release removal. This Job removes the ClickHouseInstallation and runs orphan cleanup for StatefulSets, Pods, and Services related to the CHI.

PVCs are preserved by default. The cleanup also does not directly remove the Altinity Operator Deployment.