Перейти к основному содержанию
В этом документе представлен обзор ключевых понятий и сценариев использования ClickHouse Operator.

​
Что такое ClickHouse Operator

ClickHouse Operator — это оператор Kubernetes, который автоматизирует развертывание и управление кластерами ClickHouse в Kubernetes. Он построен на основе паттерна operator и расширяет API Kubernetes пользовательскими ресурсами, представляющими кластеры ClickHouse и их зависимости. Оператор выполняет следующие задачи:
  • Управление жизненным циклом кластера (создание, обновление, масштабирование, удаление)
  • Координация кластера ClickHouse Keeper
  • Автоматическая генерация конфигурации
  • Синхронизация схемы базы данных
  • Поэтапные обновления и обновления версий
  • Подготовка хранилища

​
Пользовательские ресурсы

Оператор включает два основных CRD (определения пользовательских ресурсов):

​
ClickHouseCluster

Описывает кластер баз данных ClickHouse с настраиваемыми репликами и сегментами. 
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

​
KeeperCluster

Представляет кластер ClickHouse Keeper для распределённой координации (заменяет ZooKeeper). 
apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

​
Координация

​
ClickHouse Keeper обязателен

Для каждого ClickHouseCluster требуется кластер ClickHouse Keeper для распределенной координации. В спецификации ClickHouseCluster на кластер Keeper нужно сослаться с помощью keeperClusterRef. По умолчанию оператор ищет его в пространстве имен ClickHouseCluster, но при необходимости можно также задать keeperClusterRef.namespace, чтобы указать на KeeperCluster в другом отслеживаемом пространстве имен.

​
Связь Keeper «один к одному»

У каждого ClickHouseCluster должен быть собственный выделенный KeeperCluster. Нельзя использовать один KeeperCluster для нескольких ClickHouseClusters. Почему? Оператор автоматически создает уникальный ключ аутентификации для каждого ClickHouseCluster, чтобы он мог подключаться к своему Keeper. Этот ключ хранится в Secret и не может использоваться совместно. Последствия:
  • Несколько ClickHouseClusters не могут ссылаться на один и тот же KeeperCluster
  • При повторном создании ClickHouseCluster необходимо также повторно создать его KeeperCluster
Persistent Volumes не удаляются автоматически при удалении ресурсов ClickHouseCluster или KeeperCluster.
При повторном создании кластера:
  1. Удалите ресурс ClickHouseCluster
  2. Удалите ресурс KeeperCluster
  3. Дождитесь завершения работы всех подов
  4. При необходимости удалите PersistentVolumeClaims, если хотите начать с чистого листа
  5. Повторно создайте KeeperCluster и ClickHouseCluster вместе
Чтобы избежать ошибок аутентификации, либо удалите Persistent Volumes вручную, либо заново создайте оба кластера с новым хранилищем.

​
Репликация схемы

ClickHouse Operator автоматически реплицирует определения базы данных между всеми репликами кластера.

​
Что реплицируется

Оператор синхронизирует:
  • определения баз данных Replicated
  • движки баз данных для интеграции (PostgreSQL, MySQL и т. д.)
Оператор не синхронизирует:
  • базы данных без репликации (Atomic, Ordinary и т. д.)
  • локальные таблицы в базах данных без репликации
  • данные таблиц (это обрабатывается репликацией ClickHouse)
РекомендацияВсегда используйте движок базы данных Replicated для production-развертываний.
Преимущества:
  • Автоматическая репликация схемы между всеми узлами
  • Упрощенное управление таблицами
  • Оператор может синхронизироваться с новыми репликами
  • Согласованная схема во всем кластере
Создавайте базы данных с использованием распределенного DDL: 
CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

​
Избегайте нереплицируемых движков

Нереплицируемые движки баз данных (Atomic, Lazy, SQLite, Ordinary) требуют ручного управления схемой:
  • Таблицы необходимо создавать отдельно на каждой реплике
  • Между узлами возможны расхождения схемы
  • Оператор не может автоматически синхронизировать новые реплики

​
Отключение репликации схемы

Чтобы отключить автоматическую репликацию схемы, установите для spec.settings.enableDatabaseSync значение false в ресурсе ClickHouseCluster.

​
Управление хранилищем

Оператор управляет хранилищем с помощью объектов Kubernetes PersistentVolumeClaim (PVC).

​
Настройка тома данных

Укажите требования к хранилищу в dataVolumeClaimSpec: 
spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi

​
Жизненный цикл хранилища

  • Создание: PVC создаются автоматически вместе с кластером
  • Расширение: Поддерживается, если StorageClass допускает расширение томов
  • Сохранение: PVC не удаляются автоматически при удалении кластера
  • Повторное использование: Существующие PVC можно повторно использовать, если кластер создаётся заново с тем же именем
Чтобы полностью удалить хранилище: 
# Удалить кластер
kubectl delete clickhousecluster my-cluster

# Дождаться завершения подов
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster

# Удалить PVC
kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster

​
Основные особенности конфигурации по умолчанию

  • Предварительно настроенный кластер: кластер с именем default, включающий все узлы ClickHouse.
  • Макросы по умолчанию: некоторые полезные макросы уже определены:
    • {cluster}: имя кластера (default)
    • {shard}: номер сегмента
    • {replica}: номер реплики
  • Реплицируемое хранилище для сущностей RBAC
  • Реплицируемое хранилище для пользовательских функций (UDF)

​
Следующие шаги

Последнее изменение 10 июня 2026 г.