ClickHouse Configuration

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

What is ClickHouse?

ClickHouse is a high-performance columnar database designed for analytics.

Instead of storing data row by row (like PostgreSQL), it stores data column by column — enabling extremely fast reads when you need to aggregate large volumes of data (sum of sales by month, averages, counts).

In TDP Kubernetes, ClickHouse is used as the destination for already-processed data: pipelines load transformed data into it, and tools such as Superset and CloudBeaver query that data for analysis and visualization.

Learn more

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

The operator model: Altinity ClickHouse Operator

The chart uses the Altinity ClickHouse Operator, which works similarly to Strimzi for Kafka: you describe the desired state of the cluster in a Kubernetes resource called ClickHouseInstallation (CHI), and the operator takes care of creating and maintaining the corresponding Pods, Services, and PVCs.

This means that after installing the chart, you will see a chi resource in the cluster (in addition to the Pods and Services).

Most advanced customizations are done via extraConfig (ClickHouse XML) or via commented blocks in values.yaml.

Deployed components

Component	Description
Altinity Operator	Manages the lifecycle of the ClickHouseInstallation
ClickHouseInstallation	CRD that defines the cluster: shards, replicas, storage
TDP User Job (optional)	Creates a dedicated TDP user with appropriate grants
S3 Job (optional)	Creates an S3 bucket and connection Secret for ClickHouse
Cleanup Job	Removes ClickHouse resources before uninstalling the chart

Overview

The package includes, among others:

• Optional operator deployment (chart dependency)
• ClickHouse cluster deployment (ClickHouseInstallation)
• Persistent storage
• Optional TDP integrations: bucket/S3 Secret job (TDPConfigurations.s3Connection), dedicated TDP user and grants job, pre-delete cleanup job

Prerequisites

• Kubernetes and Helm 3
• A default StorageClass or tdp-clickhouse.clickhouse.persistence.storageClass defined

Installation (OCI)

Terminal input

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

All options are available in the helm show values export; use a private values file for overrides.

Main parameters

Parameter	Description	Default (reference)
tdp-clickhouse.clickhouse.enabled	Enable cluster	true
tdp-clickhouse.clickhouse.persistence.*	PVC (size, storageClass, accessModes)	see helm show values
tdp-clickhouse.clickhouse.resources	CPU and memory requests/limits	see helm show values
tdp-clickhouse.clickhouse.defaultUser.password	Default user password	""
tdp-clickhouse.clickhouse.tdpUser.enabled	TDP user + grants job	false
tdp-clickhouse.operator.enabled	Altinity Operator	true
tdp-clickhouse.cleanup.enabled	Pre-delete cleanup job	true
TDPConfigurations.s3Connection.*	Bucket/S3 Secret (optional job)	disabled by default

Resources (CPU and memory)

tdp-clickhouse:
  clickhouse:
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

Attention

Use the prefix tdp-clickhouse.clickhouse.resources (not tdp-clickhouse.resources on its own).

High availability (HA)

The values export includes commented example blocks (shards/replicas, optional Keeper, etc.). Uncomment and adjust only when needed.

To inspect the cluster after deployment:

Terminal input

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

For diagnostic queries, use a ClickHouse pod listed by the operator labels (the exact name depends on the ClickHouseInstallation):

Terminal input

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

Replace <chi-name> with the name of the chi resource in your environment (kubectl get chi -n <namespace>).

TDPConfigurations.s3Connection (optional)

When enabled: true, a job attempts to create the bucket (if it does not exist) and generates the Secret tdp-clickhouse-s3-connection. Use placeholders and store credentials outside Git:

TDPConfigurations:
  s3Connection:
    enabled: true
    bucket: "<s3-bucket-name>"
    accessKey: "<s3-access-key>"
    secretKey: "<s3-secret-key>"
    uri: "https://<s3-endpoint>"
    selfSigned: false

ClickHouse itself uses S3 via tdp-clickhouse.clickhouse.extraConfig (XML), aligned to this endpoint — follow the complete example in helm show values and the ClickHouse documentation.

Optional TDP user

• tdp-clickhouse.clickhouse.tdpUser.enabled: creates a Secret (tdp-clickhouse-tdp-user) and a post-install/upgrade job for grants.
• Password: provide via a private values file (tdp-clickhouse.clickhouse.tdpUser.password).

Access

Port-forward (HTTP)

Terminal input

kubectl -n <namespace> port-forward svc/<service-name> 8123:8123
curl "http://localhost:8123/?query=SELECT%201"

<service-name> is the ClickHouse HTTP Service generated by the chart/release (see kubectl get svc -n <namespace>).

Name resolution

For S3 endpoints or other targets reachable only by custom hostname, ensure DNS resolution in the cluster (e.g. CoreDNS/ExternalDNS) or, if applicable to your environment, equivalent entries in the pod — avoid documenting fixed IPs here.

Troubleshooting

Terminal input

kubectl -n <namespace> get pods
kubectl -n <namespace> get chi
kubectl -n <namespace> logs deployment/<operator-deployment-name>
kubectl -n <namespace> logs -l clickhouse.altinity.com/chi=<chi-name>

Uninstallation

Terminal input

helm -n <namespace> uninstall <release>