Мониторинг ClickHouse Operator

Как собирать, защищать и использовать метрики оператора и конечные точки проверки работоспособности.

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

В этом руководстве описано, какие данные предоставляет оператор, как их собирать и какие запросы полезны в повседневной работе.

Это руководство посвящено самому процессу оператора (controller manager). Для метрик ClickHouse server (запросы, части, задержка репликации) используйте конечную точку Prometheus в ClickHouse, чтобы собирать их отдельно.

​

Конечные точки

Процесс оператора предоставляет две HTTP-конечные точки в поде manager:

Конечная точка	Порт по умолчанию	Путь	Назначение
Метрики	8080 (Helm) / 0 — отключено (по умолчанию для бинарного файла)	/metrics	Формат экспозиции Prometheus
Проверка состояния	8081	/healthz, /readyz	Проверки работоспособности и готовности в Kubernetes

Конечная точка метрик по умолчанию отключена, если запускать бинарный файл оператора напрямую (--metrics-bind-address=0). Helm-чарт включает её с помощью metrics.enable: true и metrics.port: 8080.

Конечная точка проверки состояния всегда включена; шаблон развертывания связывает /healthz и /readyz с проверками работоспособности и готовности пода на порту 8081.

​

Флаги бинарного файла оператора

Соответствующие флаги manager (определены в cmd/main.go):

Flag	Default	Description
--metrics-bind-address	0 (отключено)	Адрес привязки для конечной точки метрик. Укажите :8443 для HTTPS или :8080 для HTTP. Оставьте 0, чтобы отключить сервер метрик.
--metrics-secure	true	Отдавать метрики по HTTPS с аутентификацией и авторизацией. Установите false, чтобы использовать обычный HTTP.
--metrics-cert-path	пусто	Каталог с файлами TLS-сертификата (tls.crt, tls.key) для сервера метрик.
--metrics-cert-name	tls.crt	Имя файла сертификата внутри --metrics-cert-path.
--metrics-cert-key	tls.key	Имя файла ключа внутри --metrics-cert-path.
--enable-http2	false	Включить HTTP/2 для серверов метрик и вебхука. По умолчанию отключено для снижения риска CVE-2023-44487 / CVE-2023-39325.
--leader-elect	false (бинарный файл) / true (Helm-чарт)	Включить выбор лидера, чтобы в каждый момент времени только одна реплика выполняла сверку состояния. Helm-чарт по умолчанию задаёт этот флаг в manager.args.
--health-probe-bind-address	:8081	Адрес привязки для /healthz и /readyz.

Соглашение 8443 (HTTPS) / 8080 (HTTP) в тексте справки для флага — лишь подсказка. Helm-чарт обслуживает HTTPS на 8080, потому что задаёт и metrics.port: 8080, и metrics.secure: true. Автоопределения режима по порту нет — HTTP или HTTPS выбирается через --metrics-secure.

​

Включение метрик через Helm

Чарт уже создаёт Service для порта метрик и, при необходимости, ServiceMonitor для prometheus-operator.

Сама конечная точка метрик включена по умолчанию (metrics.enable: true, порт 8080, доступна по HTTPS через metrics.secure: true). Обычно достаточно изменить только параметр prometheus.enable, чтобы чарт создал ServiceMonitor за вас:

# values.yaml — minimal override
prometheus:
  enable: true

Если вы не используете cert-manager, дополнительно задайте certManager.enable: false, и тогда ServiceMonitor будет собирать метрики с insecureSkipVerify: true, полагаясь только на аутентификацию по bearer-токену.

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

metrics:
  enable: true
  port: 8080
  secure: true            # HTTPS with authn/authz enforced on every scrape

certManager:
  enable: true            # Issues the metrics server certificate

prometheus:
  enable: false           # Set to true to render the ServiceMonitor
  scraping_annotations: false   # Alternative: prometheus.io/scrape pod annotations

Применить:

helm upgrade --install clickhouse-operator \
  oci://ghcr.io/clickhouse/clickhouse-operator-helm \
  -n clickhouse-operator-system --create-namespace \
  -f values.yaml

После установки чарт создаёт:

• Service/<resource-prefix>-metrics-service — предоставляет порт 8080 (HTTPS, если metrics.secure: true).
• ServiceMonitor/<resource-prefix>-controller-manager-metrics-monitor — если prometheus.enable: true.
• ClusterRole/<resource-prefix>-metrics-reader — нересурсный URL /metrics с правом get.

​

Защита конечной точки метрик

Если задано metrics.secure: true, сервер метрик требует TLS и аутентификацию/авторизацию Kubernetes при каждом опросе. Scraper’ы должны:

1. Предъявлять действительный Kubernetes Bearer-токен.
2. Использовать ServiceAccount, привязанный к РольКластера, которая предоставляет get для нересурсного URL /metrics.

В chart входит такая РольКластера:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: clickhouse-operator-metrics-reader
rules:
  - nonResourceURLs:
      - /metrics
    verbs:
      - get

Привяжите его к ServiceAccount, который использует ваш скрейпер (обычно Prometheus):

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus-clickhouse-operator-metrics-reader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: clickhouse-operator-metrics-reader
subjects:
  - kind: ServiceAccount
    name: <prometheus-sa>
    namespace: <prometheus-namespace>

Если вы видите 401 Unauthorized или 403 Forbidden от конечной точки метрик, значит, сборщик использует HTTPS, но у него отсутствует Bearer-токен Kubernetes или нет прав на его использование, либо у его ServiceAccount нет привязки, указанной выше. Отключать защиту, установив metrics.secure: false, не рекомендуется в общих кластерах, поскольку любой, у кого есть сетевой доступ к поду, сможет собирать метрики с этой конечной точки.

​

Справочник по ServiceMonitor

Чарт создаёт ServiceMonitor следующего вида, если prometheus.enable: true:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: <release>-controller-manager-metrics-monitor
  namespace: <operator-namespace>
  labels:
    control-plane: controller-manager
spec:
  selector:
    matchLabels:
      control-plane: controller-manager
  endpoints:
    - path: /metrics
      port: https           # "http" when metrics.secure: false
      scheme: https
      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
      tlsConfig:
        serverName: <release>-metrics-service.<operator-namespace>.svc
        ca:
          secret:
            name: metrics-server-cert
            key: ca.crt
        cert:
          secret:
            name: metrics-server-cert
            key: tls.crt
        keySecret:
          name: metrics-server-cert
          key: tls.key

Если в вашем экземпляре Prometheus не запущен cert-manager, установите tlsConfig.insecureSkipVerify: true и используйте только аутентификацию по bearer-токену — чарт уже делает это, когда certManager.enable: false.

​

Автономный пример Prometheus

Если вы не используете kube-prometheus-stack, в репозитории доступен автономный пример: examples/prometheus_secure_metrics_scraper.yaml. Он создаёт ServiceAccount, необходимые объекты RBAC и ресурс Prometheus (CR), который выбирает ServiceMonitor оператора.

​

Конечные точки проверки состояния

Path	Используется для	Возвращает
/healthz	проверки работоспособности Kubernetes	200 OK, пока сервер проб прослушивает порт.
/readyz	проверки готовности Kubernetes	200 OK, пока сервер проб прослушивает порт.

Обе конечные точки регистрируются с одной и той же простой ping-проверкой (healthz.Ping из sigs.k8s.io/controller-runtime). Поэтому сбой пробы означает “процесс manager не обслуживает HTTP на :8081”, а не “с контроллерами что-то не так”. Чтобы выявлять проблемы на уровне контроллеров, используйте вместо этого метрики реконсиляции.

Обе конечные точки по умолчанию доступны на порту 8081. Они подключены к развертыванию следующим образом:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8081
  initialDelaySeconds: 15
  periodSeconds: 20
readinessProbe:
  httpGet:
    path: /readyz
    port: 8081
  initialDelaySeconds: 5
  periodSeconds: 10

Постоянно завершающаяся с ошибкой probe обычно означает, что сам probe-сервер так и не запустился — например, менеджер завершил работу на раннем этапе запуска. Проверьте журналы менеджера на наличие unable to start manager, сбоев RBAC или ошибок cache did not sync.

​

Каталог метрик

Оператор не регистрирует пользовательские коллекторы Prometheus. Всё перечисленное ниже экспортируется библиотеками controller-runtime и client-go, лежащими в основе оператора. Ниже приведены наиболее полезные серии, сгруппированные по назначению:

​

Активность реконсиляции

Метрика	Тип	Метки
controller_runtime_reconcile_total	counter	controller, result (success / error / requeue / requeue_after)
controller_runtime_reconcile_errors_total	counter	controller
controller_runtime_reconcile_time_seconds_bucket	histogram	controller
controller_runtime_active_workers	gauge	controller
controller_runtime_max_concurrent_reconciles	gauge	controller

Метка controller определяется в controller-runtime на основе типа ресурса, зарегистрированного через For(...). В текущем коде в internal/controller/clickhouse и internal/controller/keeper это будут clickhousecluster и keepercluster соответственно. Если вы изменяли оператор, проверьте это с помощью однократного сбора /metrics.

​

Рабочая очередь

Метрика	Тип	Метки
workqueue_depth	gauge	name, controller, priority
workqueue_adds_total	counter	name, controller
workqueue_retries_total	counter	name, controller
workqueue_unfinished_work_seconds	gauge	name, controller
workqueue_longest_running_processor_seconds	gauge	name, controller
workqueue_queue_duration_seconds_bucket	histogram	name, controller
workqueue_work_duration_seconds_bucket	histogram	name, controller

Метки name и controller имеют одно и то же значение (имя контроллера).

​

Трафик API-сервера

Метрика	Тип	Метки
rest_client_requests_total	Counter	code, method, host

​

Выбор лидера

Метрика	Тип	Метки
leader_election_master_status	gauge	name (= d4ceba06.clickhouse.com)

В Helm-чарте флаг --leader-elect включён по умолчанию, поэтому эта метрика присутствует в стандартных установках через Helm. При запуске бинарного файла напрямую без этого флага метрика отсутствует.

​

Среда выполнения

Стандартные коллекторы метрик процесса Go и среды выполнения — go_goroutines, go_memstats_*, process_cpu_seconds_total, process_resident_memory_bytes и т. д.

​

Полезные запросы PromQL

​

Обзор состояния

# Reconciliation rate per controller
sum by (controller) (rate(controller_runtime_reconcile_total[5m]))

# Error rate per controller (alert if > 0 sustained)
sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m]))

# p99 reconcile latency
histogram_quantile(
  0.99,
  sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[5m]))
)

​

Выявление накопления очереди

# Pending items in the work queue — a sustained value > 0 indicates a backlog,
# but short spikes during large reconciles are normal.
avg_over_time(workqueue_depth[10m])

# Reconciles that have been running for a long time
workqueue_longest_running_processor_seconds > 60

​

Троттлинг и нагрузка на API

# Throttled requests to the API server
sum by (code, host) (rate(rest_client_requests_total{code=~"4..|5.."}[5m]))

​

Статус лидера (HA-развертывание)

# Should be exactly 1 across the replica set (Helm install enables --leader-elect by default)
sum(leader_election_master_status{name="d4ceba06.clickhouse.com"})

​

Рекомендуемые оповещения

Отправная точка для PrometheusRule (настройте пороговые значения под свою среду):

groups:
  - name: clickhouse-operator
    rules:
      - alert: ClickHouseOperatorReconcileErrors
        # > 0.1 errors/s sustained = > ~6 errors/min, filters transient conflicts.
        expr: sum by (controller) (rate(controller_runtime_reconcile_errors_total[5m])) > 0.1
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: 'ClickHouse operator is failing to reconcile {{ $labels.controller }}'

      - alert: ClickHouseOperatorWorkqueueBacklog
        # avg_over_time avoids alerting on transient bursts during large reconciles.
        expr: avg_over_time(workqueue_depth[10m]) > 5
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: 'Operator work queue backlog sustained for 30m'

      - alert: ClickHouseOperatorReconcileSlow
        expr: |
          histogram_quantile(
            0.99,
            sum by (le, controller) (rate(controller_runtime_reconcile_time_seconds_bucket[10m]))
          ) > 30
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: 'p99 reconcile latency for {{ $labels.controller }} > 30s'

      - alert: ClickHouseOperatorNoLeader
        expr: absent(leader_election_master_status{name="d4ceba06.clickhouse.com"}) == 1
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: 'No leader for the ClickHouse operator (HA deployment)'

Последнее правило имеет смысл, только если включен механизм выбора лидера.

​

Проверка установки

Краткая сквозная проверка, если чарт установлен в clickhouse-operator-system:

NS=clickhouse-operator-system

# The metrics Service exists and selects the manager pod
kubectl -n $NS get svc -l control-plane=controller-manager

# The ServiceMonitor exists (only with prometheus.enable=true)
kubectl -n $NS get servicemonitor -l control-plane=controller-manager

# Manager pod is Ready (readiness probe answers)
kubectl -n $NS get pod -l control-plane=controller-manager

# Direct scrape from inside the cluster (with the metrics-reader binding)
kubectl -n $NS run curl-metrics --rm -it --restart=Never \
  --image=curlimages/curl:8.10.1 -- sh -c '
    TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
    curl -sk -H "Authorization: Bearer $TOKEN" \
      https://<release>-metrics-service.'$NS'.svc:8080/metrics \
      | head -20
  '

Если при скрейпинге возвращаются метрики в формате экспозиции Prometheus, конечная точка и RBAC настроены правильно.

​

Связанные руководства

• Установка — значения Helm для мониторинга.
• Конфигурация — настройка TLS, общая с сервером метрик.