Часть 2. Операторы: официальный от ClickHouse Inc. и Altinity

Разворачивать ClickHouse в Kubernetes «голыми» StatefulSet’ами можно, но вы быстро упрётесь в генерацию XML-конфигов, макросы, связку с Keeper, порядок обновлений и распространение схемы. Всё это уже умеют операторы.

Важное изменение ландшафта: долгие годы стандартом де-факто был оператор Altinity, но в 2025 году ClickHouse Inc. выпустила собственный, первопартийный оператор. Теперь их два, и выбор зависит от того, что вы строите.

Официальный оператор ClickHouse

Написан на Kubebuilder, распространяется под Apache-2.0, живёт в ClickHouse/clickhouse-operator . Ставит два CRD:

clickhouseclusters.clickhouse.com — сам кластер БД;
keeperclusters.clickhouse.com — кластер координации.

Оператор создаёт StatefulSet’ы, Service’ы, PVC и PodDisruptionBudget, связывает кластер с Keeper, ведёт rolling-обновления с отслеживанием ревизий и отдаёт метрики Prometheus.

Требования и установка

Нужен Kubernetes 1.28+ (свежие релизы поднимают планку — сверяйтесь с README) и обязательно cert-manager — он выпускает сертификаты для webhook’ов. Без него установка молча не заведётся.

BASH

kubectl apply --server-side --force-conflicts \
  -f https://github.com/ClickHouse/clickhouse-operator/releases/latest/download/clickhouse-operator.yaml
Нажмите, чтобы развернуть и увидеть больше

Есть также установка через Helm и через OLM (для OpenShift).

Минимальный кластер

Сначала координация, затем сам ClickHouse со ссылкой на неё:

YAML

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    accessModes: [ReadWriteOnce]
    resources:
      requests:
        storage: 1Gi
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    accessModes: [ReadWriteOnce]
    resources:
      requests:
        storage: 1Gi
  keeperClusterRef:
    name: sample
Нажмите, чтобы развернуть и увидеть больше

Ключевая строка здесь — keeperClusterRef. Это склейка кластера с координацией. Забудете её — поды поднимутся и всё будет выглядеть здоровым, но репликации не будет: вы получите два независимых узла, которые молча расходятся в данных. Это, пожалуй, самая коварная ошибка новичка.

Что смотреть в статусе

Оператор отдаёт понятный status, по которому строится автоматика и дежурные проверки:

conditions — Ready, ConfigurationInSync, ReplicaStartupSucceeded, Healthy;
observedGeneration — какое поколение спеки оператор уже увидел;
currentRevision / updateRevision — отслеживание раскатки;
readyReplicas — сколько реплик реально обслуживают запросы.

BASH

kubectl get clickhousecluster sample -o jsonpath='{.status}' | jq
Нажмите, чтобы развернуть и увидеть больше

Полезные детали реализации: оператор разруливает коллизии PVC (переименованный кластер не прилипнет к чужим томам) и умеет применять часть изменений конфигурации без перезапуска пода.

Оператор Altinity

Altinity/clickhouse-operator , тоже Apache-2.0, требует Kubernetes 1.25+ и ClickHouse 21.11+. Основной ресурс — ClickHouseInstallation (CHI), плюс ClickHouseInstallationTemplate и ClickHouseKeeperInstallation.

Топология в CHI описывается явно — шарды и реплики задаются в разметке кластера:

YAML

apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
  name: analytics
spec:
  configuration:
    clusters:
      - name: main
        layout:
          shardsCount: 2
          replicasCount: 2
    zookeeper:
      nodes:
        - host: keeper-0.keeper-headless
        - host: keeper-1.keeper-headless
        - host: keeper-2.keeper-headless
  templates:
    volumeClaimTemplates:
      - name: data
        spec:
          accessModes: [ReadWriteOnce]
          resources:
            requests:
              storage: 500Gi
Нажмите, чтобы развернуть и увидеть больше

Сильные стороны Altinity — зрелость и гибкость шаблонов: podTemplate, volumeClaimTemplate, serviceTemplate, управление пользователями и конфигурацией, автоматическое распространение схемы при масштабировании кластера, экспорт метрик, FIPS-совместимые образы. За годы вокруг него накопился огромный пласт рецептов и ответов на Stack Overflow.

Что выбирать

Честное сравнение без предвзятости:

	Официальный (ClickHouse Inc.)	Altinity
Зрелость	Молодой (с 2025)	Годы в проде, много рецептов
Модель	2 CRD, Kubebuilder	CHI + шаблоны, очень гибко
Keeper	Первопартийный `KeeperCluster`	`ClickHouseKeeperInstallation` / внешний
Зависимости	Нужен cert-manager	Нет обязательного cert-manager
Кому	Новые инсталляции, «как в апстриме»	Существующие кластеры, сложные топологии

Практическая рекомендация:

Новый кластер — берите официальный: он первопартийный, развивается вместе с самим ClickHouse, модель проще.
Уже работаете на Altinity — не мигрируйте ради миграции. Оператор живой и поддерживаемый; переезд на другой оператор — это операция над продовыми данными, а не апгрейд ради строчки в changelog.
Экзотическая топология или тонкая настройка шаблонов подов — Altinity пока гибче.

В любом случае зафиксируйте версию оператора и читайте changelog перед обновлением: оба проекта активно развиваются, а v1alpha1 в имени API-группы официального оператора намекает, что поля ещё могут меняться.

Общие правила эксплуатации

Независимо от выбора:

Не давайте оператору удалять PVC. Проверьте политику reclaim у StorageClass (Retain для продовых данных) — иначе неаккуратный kubectl delete унесёт данные.
Держите манифесты в git и катите через GitOps. Оператор декларативен — используйте это.
Не редактируйте StatefulSet руками. Оператор вернёт своё; правьте кастомный ресурс.
Отдельный namespace под ClickHouse и Keeper, с квотами и NetworkPolicy.

Дальше: Часть 3. ClickHouse Keeper: кворум, ресурсы и грабли.