Перейти к основному содержимому
Перейти к основному содержимому

Руководство по настройке оператора ClickHouse

В этом руководстве описывается, как настраивать кластеры ClickHouse и Keeper с помощью оператора.

Конфигурация ClickHouseCluster​

Базовая конфигурация​

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # Number of replicas per shard
  shards: 2             # Number of shards
  keeperClusterRef:
    name: my-keeper     # Reference to KeeperCluster
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi

Реплики и сегменты​

  • Реплики: количество экземпляров ClickHouse в одном сегменте (для высокой доступности)
  • Сегменты: количество горизонтальных партиций (для масштабирования)
spec:
  replicas: 3  # Default: 3
  shards: 2    # Default: 1

Кластер с replicas: 3 и shards: 2 создаст в сумме 6 подов ClickHouse.

Интеграция с Keeper​

Каждый кластер ClickHouse должен быть связан с KeeperCluster для координации:

spec:
  keeperClusterRef:
    name: my-keeper  # Name of the KeeperCluster in the same namespace

Конфигурация KeeperCluster​

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # Must be odd: 1, 3, 5, 7, 9, 11, 13, or 15
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 5Gi

Конфигурация хранилища​

Настройте персистентное хранилище:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 100Gi
Примечание

Оператор может изменять существующий PVC только если базовый класс хранилища поддерживает расширение тома.

Конфигурация подов​

Автоматическое распределение подов (topology spread) и аффинность​

Распределите поды по зонам доступности:

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
Примечание

Убедитесь, что в вашем кластере Kubernetes достаточно узлов в разных зонах, чтобы соответствовать ограничениям распределения.

Ручная конфигурация​

Можно задать произвольные правила affinity/anti-affinity подов и ограничения распределения по топологии.

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

См. API Reference для описания всех поддерживаемых параметров шаблона пода.​

Конфигурация контейнера​

Собственный образ​

Укажите образ ClickHouse:

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

Ресурсы контейнеров​

Настройте ресурсы CPU и памяти для контейнеров ClickHouse:

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"

Переменные окружения​

Добавьте пользовательские переменные окружения:

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

Монтирование томов​

Добавьте дополнительные точки монтирования томов:

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml
Примечание

Допускается указывать несколько монтирований томов на один и тот же mountPath. Оператор создаст проецируемый том со всеми указанными монтированиями.

См. API Reference для описания всех поддерживаемых параметров шаблона контейнера.​

Настройка TLS/SSL​

Настройка защищённых конечных точек​

Укажите ссылку на Kubernetes Secret, содержащий TLS-сертификаты, чтобы включить защищённые конечные точки

spec:
  settings:
    tls:
      enabled: true
      required: true # Insecure ports are disabled if set
      serverCertSecret:
        name: <certificate-secret-name>

Формат секрета с SSL-сертификатом​

Предполагается, что Secret содержит следующие ключи:

  • tls.crt — серверный сертификат в формате PEM
  • tls.key — закрытый ключ в формате PEM
  • ca.crt — цепочка сертификатов CA в формате PEM
Примечание

Этот формат совместим с сертификатами, сгенерированными cert-manager.

Взаимодействие ClickHouse-Keeper через TLS​

Если в KeeperCluster включен TLS, ClickHouseCluster автоматически устанавливает защищённое соединение с узлами Keeper.

ClickHouseCluster должен иметь возможность проверять сертификаты узлов Keeper. Если в ClickHouseCluster включен TLS, для проверки используется набор ca.crt. В противном случае используется стандартный набор корневых сертификатов (CA bundle).

Пользователь может указать собственный набор корневых сертификатов (CA bundle):

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

Настройки ClickHouse​

Пароль пользователя по умолчанию​

Установите пароль пользователя по умолчанию:

spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # Default: password
      <secret|configMap>:
        name: <resource name>
        key: <password>
Примечание

Не рекомендуется использовать ConfigMap для хранения паролей в незашифрованном виде.

Создайте секрет:

kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'

Использование ConfigMap для паролей пользователей​

Вы также можете использовать ConfigMap для несекретных паролей по умолчанию:

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

Пользователи, определённые в конфигурации​

Настройте дополнительных пользователей в конфигурационных файлах.

Создайте ConfigMap и Secret для пользователя:

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          - query: "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

Добавьте собственную конфигурацию в ClickHouseCluster:

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

Синхронизация базы данных​

Включите автоматическую синхронизацию базы данных для новых реплик:

spec:
  settings:
    enableDatabaseSync: true  # Default: true

При включении этой опции оператор синхронизирует реплицируемые и интеграционные таблицы с новыми репликами.

Пользовательская конфигурация​

Встроенная дополнительная конфигурация​

Вместо монтирования пользовательских файлов конфигурации вы можете напрямую задать дополнительные параметры конфигурации ClickHouse.

Добавьте пользовательскую конфигурацию ClickHouse через параметр extraConfig:

spec:
  settings:
    extraConfig:
      background_pool_size: 20

Встроенная конфигурация дополнительных пользователей​

Вы также можете задать дополнительную конфигурацию пользователей ClickHouse с помощью extraUsersConfig. Это удобно для определения пользователей, профилей, QUOTA и привилегий непосредственно в спецификации кластера.

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100
Примечание

extraUsersConfig сохраняется в объекте k8s ConfigMap. Избегайте хранения там секретов в виде простого текста.

См. документацию со всеми поддерживаемыми параметрами конфигурации пользователей ClickHouse.​

Пример конфигурации​

Полный пример конфигурации:

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # secret-password
  password: "..." # sha256 hex of the password
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password