События Kubernetes

Оператор записывает события Kubernetes в объекты ClickHouseCluster и KeeperCluster, которыми он управляет. Эти события показывают, что оператор делал во время реконсиляции: где не удалось применить изменения ресурсов, когда кластер стал готов, почему было заблокировано масштабирование, — а также помогают выявить сбои, которые обычно не попадают в журналы, которые просматривает пользователь. Они дополняют метрики, добавляя человекочитаемую историю непосредственно в пользовательский ресурс.

clickhouse-controller сообщает о событиях для объектов ClickHouseCluster, а keeper-controller — для объектов KeeperCluster. События, связанные со сбоями жизненного цикла ресурсов, также содержат ссылку на соответствующий управляемый объект (StatefulSet, Service, ConfigMap, Secret, PodDisruptionBudget, PersistentVolumeClaim или задачу version-probe); остальные события относятся только к самому кластеру.

Быстрее всего просмотреть их с помощью kubectl describe для пользовательского ресурса: внизу будет список последних событий:

NS=<your-namespace>

kubectl -n $NS describe clickhousecluster <name>
kubectl -n $NS describe keepercluster <name>

Чтобы вывести события напрямую — например, чтобы отслеживать их в реальном времени или отфильтровать только сбои, — выполните запрос к ресурсу events и отфильтруйте результаты по связанному объекту или по типу:

# All events for one cluster, newest last
kubectl -n $NS get events \
  --field-selector involvedObject.name=<name> \
  --sort-by=.lastTimestamp

# Only warnings across the namespace
kubectl -n $NS get events --field-selector type=Warning

# Follow events as they arrive
kubectl -n $NS get events --watch

В источнике события отображается контроллер, создавший его, поэтому вы можете отличить событие ClickHouseCluster (clickhouse-controller) от события KeeperCluster (keeper-controller).

Оператор формирует фиксированный набор причин, сгруппированных по тому, что они описывают. События Normal обозначают штатный ход выполнения; события Warning сообщают о сбое или состоянии, требующем вмешательства пользователя.

Возникает как для ClickHouseCluster, так и для KeeperCluster, когда оператору не удаётся применить принадлежащий ему ресурс в ходе реконсиляции.

Генерируется для обоих типов, когда кластер переходит через порог готовности.

Создаётся для KeeperCluster, когда оператор изменяет количество реплик.

Генерируется для ClickHouseCluster, когда кластер ссылается на внешний Secret, который оператор не может использовать. См. описание возможности External Secret в руководстве по настройке.

Генерируются проверками версий для ClickHouseCluster и KeeperCluster. VersionProbeFailed относится только к задаче version-probe для ClickHouse.

Эта последняя причина отличается: она не описывает действия самого оператора. На каждой готовой реплике оператор периодически запрашивает таблицу system.warnings на сервере и повторно публикует каждую строку как событие Warning в кластере, добавляя префикс с именем реплики, из которой она получена. Так собственные предупреждения ClickHouse о конфигурации и среде выполнения — устаревшие настройки, слишком низкие лимиты, небезопасные параметры — превращаются в события, которые можно увидеть с помощью kubectl, не открывая сеанс clickhouse-client для каждой реплики.

kubectl -n $NS get events \
  --field-selector reason=ClickHouseWarning,involvedObject.name=<name>

Оператор предоставляет три уровня обсервабилити; используйте каждый по его основному назначению:

• События (это руководство) — недавние, человекочитаемые, привязанные к объекту. Лучше всего подходят для ответа на вопрос «что только что произошло с этим кластером» и для интерактивного поиска неисправностей с помощью kubectl describe. Со временем они удаляются.
• status.conditions в пользовательском ресурсе — актуальное, сохраняемое состояние (готовность, валидность External Secret, допустимость масштабирования, синхронизация версий). Лучше всего подходят для скриптов и проверок работоспособности в GitOps. Читайте их с помощью kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'.
• Метрики — долговечные и числовые. Лучше всего подходят для панелей мониторинга и для оповещений при устойчивом уровне ошибок reconcile.

Событие Warning и условие False часто описывают одну и ту же проблему с двух сторон: событие фиксирует момент и сообщение, а условие отражает состояние, пока проблема не будет устранена.

Несколько распространённых сигналов и то, на что они указывают:

• FailedCreate / FailedUpdate повторяются — оператор не может применить ресурс. В сообщении события приводится ошибка API (отклонение на этапе допуска, квота, недопустимая спецификация). Реконсиляция выполняет повторные попытки, поэтому временная причина устранится сама; если проблема сохраняется, нужно исправить спецификацию или кластер.
• ClusterNotReady без соответствующего ClusterReady — кластер не восстанавливается. В сообщении события указаны неготовые сегменты или проблема с кворумом; проверьте соответствующие поды.
• HorizontalScaleBlocked — запланированное масштабирование приостановлено из соображений безопасности. Прочитайте сообщение, чтобы понять точное ограничение, прежде чем что-либо форсировать.
• ExternalSecretNotFound / ExternalSecretInvalid — исправьте имя Secret или его ключи; соответствующее условие ExternalSecretValid примет значение True, как только оператор сможет его использовать.
• ClickHouseWarning — проблема внутри ClickHouse, а не в операторе. Относитесь к этому сообщению так же, как к строке из system.warnings.

• Мониторинг оператора — метрики и проверки состояния, более устойчивый аналог событий.
• Масштабирование — что защищает HorizontalScaleBlocked и как кворум Keeper ограничивает масштабирование.
• Конфигурация — возможность External Secret, стоящая за событиями external-secret.