The module lifecycle stage: Preview
The module has requirements for installation

ClickhouseClass

The cluster-wide ClickhouseClass custom resource defines validation rules, sizing policies, and scheduling constraints for Clickhouse instances. Every Clickhouse resource must reference an existing ClickhouseClass. Before deployment, the operator validates the instance configuration against the selected class.

The ClickhouseClass resource is immutable. To change its specification, create a new class and update Clickhouse resources to reference it.

Sizing policies

The spec.sizingPolicies field defines allowed resource combinations for associated Clickhouse instances. This helps avoid uneven CPU and memory distribution across cluster nodes.

The operator selects a policy by matching spec.instance.cpu.cores to the cores.min–cores.max range. It then checks memory size, coreFraction, and other fields of the matched policy.

spec:
  sizingPolicies:
    - cores:
        min: 1
        max: 4
      memory:
        min: 100Mi
        max: 1Gi
        step: 1Mi
      coreFractions:
        - 10%
        - 30%
        - 50%
    - cores:
        min: 5
        max: 10
      memory:
        min: 500Mi
        max: 2Gi
      coreFractions:
        - 50%
        - 70%
        - 100%

Validation rules

Use CEL (Common Expression Language) expressions in spec.validations to define custom checks. The validating webhook evaluates rules on every create and update of a Clickhouse resource.

Predefined variables available in rule:

  • instance.memory.size (int, bytes);
  • instance.cpu.cores (int);
  • instance.persistentVolumeClaim.size (int, bytes).
spec:
  validations:
    - message: "CPU cores must be between 1 and 64"
      rule: "instance.cpu.cores >= 1 && instance.cpu.cores <= 64"

Node affinity

Standard Kubernetes mechanism for pod scheduling. Set spec.nodeAffinity to control which nodes can run ClickHouse pods.

spec:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: "node.deckhouse.io/group"
              operator: "In"
              values:
                - "ch"

Tolerations

Standard Kubernetes mechanism for scheduling pods onto tainted nodes. Set spec.tolerations in ClickhouseClass.

spec:
  tolerations:
    - key: primary-role
      operator: Equal
      value: ch
      effect: NoSchedule

Node selector

Standard Kubernetes mechanism for restricting pod placement. Set spec.nodeSelector in ClickhouseClass.

spec:
  nodeSelector:
    node.deckhouse.io/group: ch

Usage examples

Default class configuration

According to ClickHouse sizing recommendations, a universal CPU-to-RAM ratio of 1 CPU to 4 GiB is a common starting point. The default ClickhouseClass enforces this ratio.

For workloads that need ratios of 1:8 or 1:2, create a separate ClickhouseClass and reference it from Clickhouse resources.

apiVersion: managed-services.deckhouse.io/v1alpha1
kind: ClickhouseClass
metadata:
  name: default
spec:
  validations:
    - message: "The ratio of memory to cpu should be 4:1"
      rule: "instance.memory.size == instance.cpu.cores * 4 * 1024 * 1024 * 1024"
    - message: "The ratio of memory to storage should be minimum as 1:1"
      rule: "instance.persistentVolumeClaim.size >= instance.memory.size"
  sizingPolicies:
    - cores:
        min: 1
        max: 2
      memory:
        min: 4Gi
        max: 8Gi
        step: 4Gi
      coreFractions:
        - "25%"
        - "50%"
        - "75%"
        - "100%"
    - cores:
        min: 3
        max: 6
      memory:
        min: 12Gi
        max: 24Gi
        step: 4Gi
      coreFractions:
        - "75%"
        - "100%"