Справочник по API ClickHouse Operator

В этом документе приводится подробная справочная информация об API пользовательских ресурсов ClickHouse Operator.

ClickHouseCluster

ClickHouseCluster — это схема API кластера ClickHouse.

Версия API и тип ресурса

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster

ClickHouseClusterSpec

ClickHouseClusterSpec определяет желаемое состояние кластера ClickHouse.

Поле	Тип	Обязательное	По умолчанию	Описание
replicas	*int32	No	3	Количество реплик в одном сегменте. Должно быть >= 0.
shards	*int32	No	1	Количество сегментов в кластере. Должно быть >= 0.
keeperClusterRef	LocalObjectReference	Yes	-	Ссылка на KeeperCluster, используемый для координации.
podTemplate	PodTemplateSpec	No	-	Параметры спецификации пода.
containerTemplate	ContainerTemplateSpec	No	См. значения по умолчанию	Параметры спецификации контейнера ClickHouse.
dataVolumeClaimSpec	PersistentVolumeClaimSpec	Yes	-	Конфигурация хранилища для томов с данными.
labels	map[string]string	No	-	Дополнительные метки, добавляемые ко всем ресурсам.
annotations	map[string]string	No	-	Дополнительные аннотации, добавляемые ко всем ресурсам.
settings	ClickHouseConfig	No	-	Параметры конфигурации ClickHouse.

Пример

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: example-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: example-keeper
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 100Gi
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    resources:
      requests:
        cpu: "2"
        memory: "8Gi"
      limits:
        cpu: "4"
        memory: "16Gi"
  settings:
    defaultUserPassword:
      secret:
        name: clickhouse-password
        key: password
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert

ClickHouseConfig

Параметры конфигурации ClickHouse.

Поле	Тип	Обязательное	Значение по умолчанию	Описание
defaultUserPassword	*DefaultPasswordSelector	Нет	-	Пароль для пользователя «default» из Secret или ConfigMap.
logger	LoggerConfig	Нет	См. значения по умолчанию	Конфигурация логгера.
tls	ClusterTLSSpec	Нет	-	Настройки TLS для ClickHouse.
enableDatabaseSync	bool	Нет	true	Включить синхронизацию баз данных на новые реплики.
extraConfig	runtime.RawExtension	Нет	-	Дополнительная конфигурация ClickHouse (объединяется с настройками по умолчанию).
extraUsersConfig	runtime.RawExtension	Нет	-	Дополнительная конфигурация пользователей ClickHouse (объединяется с настройками по умолчанию).

ClickHouseClusterStatus

ClickHouseClusterStatus определяет наблюдаемое состояние кластера ClickHouse.

Field	Type	Description
conditions	[]metav1.Condition	Текущие состояния кластера.
observedGeneration	int64	Последнее наблюдаемое поколение.
replicas	int32	Количество реплик, в данный момент запущенных.
readyReplicas	int32	Количество готовых реплик.
configurationRevision	string	Целевая ревизия конфигурации, применённая оператором.
statefulSetRevision	string	Целевая ревизия контроллера StatefulSet.
currentRevision	string	Последняя применённая ревизия спецификации кластера.
updateRevision	string	Последняя запрошенная ревизия спецификации кластера.

KeeperCluster

KeeperCluster — это схема API для кластера ClickHouse Keeper.

Версия API и тип ресурса

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster

KeeperClusterSpec

KeeperClusterSpec определяет желаемое состояние кластера Keeper.

Field	Type	Required	Default	Description
replicas	*int32	No	3	Количество реплик. Должно быть нечётным числом: 0, 1, 3, 5, 7, 9, 11, 13 или 15.
podTemplate	PodTemplateSpec	No	-	Параметры спецификации пода.
containerTemplate	ContainerTemplateSpec	No	See defaults	Параметры спецификации контейнера Keeper.
dataVolumeClaimSpec	PersistentVolumeClaimSpec	Yes	-	Конфигурация хранилища для томов данных.
labels	map[string]string	No	-	Дополнительные метки, добавляемые ко всем ресурсам.
annotations	map[string]string	No	-	Дополнительные аннотации, добавляемые ко всем ресурсам.
settings	KeeperConfig	No	-	Параметры конфигурации Keeper.

Пример

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: example-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi
  containerTemplate:
    resources:
      requests:
        cpu: "500m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: keeper-cert

KeeperConfig

Параметры конфигурации Keeper.

Поле	Тип	Обязательно	Значение по умолчанию	Описание
logger	LoggerConfig	Нет	См. значения по умолчанию	Конфигурация логгера.
tls	ClusterTLSSpec	Нет	-	Настройки TLS для Keeper.
extraConfig	runtime.RawExtension	Нет	-	Дополнительная конфигурация Keeper (объединяется с настройками по умолчанию).

KeeperClusterStatus

KeeperClusterStatus определяет наблюдаемое состояние кластера Keeper.

Field	Type	Description
conditions	[]metav1.Condition	Текущие состояния кластера.
observedGeneration	int64	Последнее наблюдаемое поколение.
replicas	int32	Число реплик, запущенных в данный момент.
readyReplicas	int32	Число готовых реплик.
configurationRevision	string	Целевая ревизия конфигурации, применённая оператором.
statefulSetRevision	string	Целевая ревизия контроллера StatefulSet.
currentRevision	string	Последняя применённая ревизия спецификации кластера.
updateRevision	string	Последняя запрошенная ревизия спецификации кластера.

Общие типы

PodTemplateSpec

Параметры конфигурации пода.

Field	Type	Required	Description
topologyZoneKey	string	No	Ключ топологии Kubernetes для распределения по зонам (например, topology.kubernetes.io/zone).
nodeHostnameKey	string	No	Ключ метки Kubernetes для имени хоста узла (например, kubernetes.io/hostname).
nodeSelector	map[string]string	No	Селектор узла для размещения пода.
affinity	corev1.Affinity	No	Правила аффинности/антиаффинности для пода.
tolerations	[]corev1.Toleration	No	Допуски для помеченных (tainted) узлов.
securityContext	*corev1.PodSecurityContext	No	Контекст безопасности пода.

Пример

podTemplate:
  topologyZoneKey: topology.kubernetes.io/zone
  nodeHostnameKey: kubernetes.io/hostname
  nodeSelector:
    disktype: ssd
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "clickhouse"
    effect: "NoSchedule"
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: clickhouse
        topologyKey: kubernetes.io/hostname

ContainerTemplateSpec

Параметры конфигурации контейнера.

Поле	Тип	Обязательное	Описание
image	ContainerImage	Нет	Конфигурация образа контейнера.
imagePullPolicy	corev1.PullPolicy	Нет	Политика получения образа (Always, IfNotPresent, Never).
resources	corev1.ResourceRequirements	Нет	Требования к ресурсам CPU и памяти.
env	[]corev1.EnvVar	Нет	Переменные окружения.
volumeMounts	[]corev1.VolumeMount	Нет	Дополнительные точки монтирования томов.
securityContext	*corev1.SecurityContext	Нет	Контекст безопасности контейнера.

Пример

containerTemplate:
  image:
    repository: clickhouse/clickhouse-server
    tag: "25.12"
  imagePullPolicy: IfNotPresent
  resources:
    requests:
      cpu: "2"
      memory: "8Gi"
    limits:
      cpu: "4"
      memory: "16Gi"
  env:
  - name: TZ
    value: "UTC"

ContainerImage

Спецификация образа контейнера.

Поле	Тип	Обязательное	Значение по умолчанию	Описание
repository	string	Нет	ClickHouse: clickhouse/clickhouse-server Keeper: clickhouse/clickhouse-keeper	Репозиторий образа контейнера.
tag	string	Нет	latest	Тег образа.

ClusterTLSSpec

Конфигурация TLS для кластеров.

Поле	Тип	Обязательное	Описание
enabled	bool	Нет	Включить TLS.
required	bool	Нет	Требовать TLS для всех подключений (отключает небезопасные конечные точки).
serverCertSecret	corev1.LocalObjectReference	Нет	Secret, содержащий серверный сертификат (tls.crt, tls.key).
caBundle	*SecretKeySelector	Нет	Secret, содержащий набор CA-сертификатов для проверки.

Пример

tls:
  enabled: true
  required: true
  serverCertSecret:
    name: clickhouse-cert
  caBundle:
    secretKeyRef:
      name: ca-cert-secret
      key: ca.crt

LoggerConfig

Конфигурация логирования для ClickHouse и Keeper.

Field	Type	Required	Default	Description
logToFile	bool	No	true	Запись логов в файл.
level	string	No	"trace"	Уровень логирования: trace, debug, information, warning, error.
size	string	No	"1000M"	Максимальный размер файла логов.
count	int	No	50	Количество файлов логов, которые необходимо хранить.

Пример

logger:
  logToFile: true
  level: "information"
  size: "1000M"
  count: 50

DefaultPasswordSelector

Ссылка на ключ в объекте Secret или ConfigMap, содержащий пароль.

Field	Type	Required	Default	Description
passwordType	string	No	plaintext	Тип кодирования пароля. Возможные значения: plaintext, sha256_password, sha256_hash, double_sha1_password, double_sha1_hash. Подробности см. в документации ClickHouse.
secret	*SecretKeySelector	No	-	Выбор пароля из ключа объекта Secret. Взаимоисключим с configMap.
configMap	*ConfigMapKeySelector	No	-	Выбор пароля из ключа объекта ConfigMap. Взаимоисключим с secret.

Примечание

Необходимо указать либо secret, либо configMap, но не оба одновременно.

Пример с Secret (рекомендуемый)

defaultUserPassword:
  passwordType: plaintext  # Optional, default
  secret:
    name: clickhouse-password
    key: password

Пример с SHA-256

defaultUserPassword:
  passwordType: sha256_password
  secret:
    name: clickhouse-password
    key: password_hash

Пример использования ConfigMap

defaultUserPassword:
  passwordType: plaintext
  configMap:
    name: clickhouse-config
    key: default_password

Значения по умолчанию

Параметры ClickHouse по умолчанию

Параметр	Значение по умолчанию
Реплики	3
Сегменты	1
Репозиторий образа	clickhouse/clickhouse-server
Тег образа	latest
Политика загрузки образа	IfNotPresent
Запрос CPU	2
Лимит CPU	4
Запрос памяти	4Gi
Лимит памяти	8Gi
Уровень логирования	trace
Логирование в файл	true
Размер журнала	1000M
Количество файлов журнала	50
Включить синхронизацию базы данных	true

Параметры Keeper по умолчанию

Параметр	Значение по умолчанию
Реплики	3
Репозиторий образа	clickhouse/clickhouse-keeper
Тег образа	latest
Политика извлечения образа	IfNotPresent
Запрос на CPU	500m
Лимит CPU	1
Запрос памяти	512Mi
Лимит памяти	1Gi
Уровень логирования	trace
Логирование в файл	true
Размер файла лога	1000M
Количество файлов лога	50

Состояния

Состояния ClickHouseCluster

Type	Description
SpecValid	Проходит ли CustomResource ClickHouseCluster валидацию. Полезно при развертывании без webhooks
ReconcileSucceeded	Успешность последнего цикла согласования
ReplicaStartupSucceeded	Могут ли все реплики ClickHouseCluster успешно запускаться
Healthy	Готовность всех запрошенных реплик
ClusterSizeAligned	В кластере столько же реплик/сегментов, сколько запрошено
ConfigurationInSync	Отражает состояние развертывания конфигурации
Ready	ClickHouseCluster готов обслуживать клиентские запросы. Как минимум одна реплика в каждом сегменте находится в состоянии Ready
SchemaInSync	Все реплики имеют одинаковую схему базы данных после операций масштабирования

Условия KeeperCluster

Тип	Описание
SpecValid	Проходит ли пользовательский ресурс KeeperCluster проверку. Полезно в развертываниях без вебхуков.
ReconcileSucceeded	Успешность последнего цикла согласования.
ReplicaStartupSucceeded	Успешный запуск всех реплик KeeperCluster.
Healthy	Готовность всех запрошенных реплик.
ClusterSizeAligned	Размер кластера соответствует запрошенному числу реплик.
ConfigurationInSync	Отражает состояние развертывания конфигурации.
Ready	KeeperCluster готов обслуживать клиентские запросы. Лидер выбран.