User guide

Clickhouse

The Clickhouse namespaced custom resource describes a ClickHouse instance and is the source of truth for its desired state in a user namespace.

clickhouseClassName

Name of the ClickhouseClass used to validate the instance configuration. A Clickhouse resource cannot be deployed without an existing ClickhouseClass.

spec:
  clickhouseClassName: default

instance

Section that describes compute and storage resources for the ClickHouse instance. Values must match a sizing policy of the selected class.

spec:
  instance:
    memory:
      size: 4Gi
    cpu:
      cores: 1
      coreFraction: 50%
    persistentVolumeClaim:
      size: 8Gi
      storageClassName: default

TLS

The spec.tls section configures server-side TLS for ClickHouse. When TLS is enabled, unencrypted ports are disabled and clients connect over HTTPS (8443) or secure TCP (9440).

Supported modes:

• CertManager — the operator issues a certificate through cert-manager. Specify either clusterIssuerName or issuerName in spec.tls.certManager.
• CustomCertificate — use existing Secrets with tls.crt/tls.key and ca.crt. Set spec.tls.customCertificate.serverTLSSecret and spec.tls.customCertificate.serverCASecret.

spec:
  tls:
    mode: CertManager
    certManager:
      clusterIssuerName: selfsigned

If spec.tls is omitted, ClickHouse listens on HTTP port 8123 and TCP port 9000 without encryption.

Supported ClickHouse versions

The module supports only ClickHouse version 26.3.12.3-lts.

ClickHouse container images are based on the distroless architecture.

Status

The Clickhouse resource status reflects the state of the deployed service. The conditions field shows whether configuration is valid and the instance is ready.

Significant condition types:

• LastValidConfigurationApplied — whether the last valid configuration was applied at least once.
• ConfigurationValid — whether the configuration passed all validations of the associated ClickhouseClass.
• ScaledToLastValidConfiguration — whether the number of running replicas matches the specified configuration.
• Available — whether enough replicas are running and accepting connections.

conditions:
  - lastTransitionTime: '2025-09-22T23:20:36Z'
    observedGeneration: 2
    status: 'True'
    type: Available
  - lastTransitionTime: '2025-09-22T14:38:04Z'
    observedGeneration: 2
    status: 'True'
    type: ConfigurationValid
  - lastTransitionTime: '2025-09-22T14:38:47Z'
    observedGeneration: 2
    status: 'True'
    type: LastValidConfigurationApplied
  - lastTransitionTime: '2025-09-22T23:20:36Z'
    observedGeneration: 2
    status: 'True'
    type: ScaledToLastValidConfiguration

A False status indicates a problem or incomplete reconciliation. In this case, check reason and message for details.

  - lastTransitionTime: '2025-09-23T14:53:33Z'
    message: Syncing
    observedGeneration: 1
    reason: Syncing
    status: 'False'
    type: LastValidConfigurationApplied
  - lastTransitionTime: '2025-09-23T14:54:58Z'
    message: Not all the instances are running still waiting for 1 to become ready
    observedGeneration: 1
    reason: ScalingInProgress
    status: 'False'
    type: ScaledToLastValidConfiguration

Usage examples

Basic usage

Choose the memory-to-storage ratio according to the ClickHouse sizing recommendations.

1. Create a Clickhouse resource in the default namespace:

d8 k apply -f managed-services_v1alpha1_clickhouse.yaml

apiVersion: managed-services.deckhouse.io/v1alpha1
kind: Clickhouse
metadata:
  name: clickhouse-sample
spec:
  clickhouseClassName: default
  instance:
    memory:
      size: "4Gi"
    cpu:
      cores: 1
      coreFraction: "50%"
    persistentVolumeClaim:
      size: "8Gi"

2. Wait until the instance is ready and all conditions are True:

d8 k get clickhouse clickhouse-sample -o wide -w

3. Connect with clickhouse-client through the d8ms-ch-clickhouse-sample service:

clickhouse-client -h d8ms-ch-clickhouse-sample