> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# События Kubernetes

> Как оператор сообщает о сбоях реконсиляции, ходе масштабирования, проверках версий и предупреждениях сервера ClickHouse в виде событий Kubernetes для объектов ClickHouseCluster и KeeperCluster, как их просматривать и что означает каждая причина события.

Оператор записывает события Kubernetes в объекты `ClickHouseCluster` и
`KeeperCluster`, которыми он управляет. Эти события показывают, что оператор делал
во время реконсиляции: где не удалось применить изменения ресурсов, когда кластер стал
готов, почему было заблокировано масштабирование, — а также помогают выявить сбои, которые обычно не попадают в журналы, которые просматривает пользователь. Они дополняют [метрики](/docs/ru/products/kubernetes-operator/guides/monitoring),
добавляя человекочитаемую историю непосредственно в пользовательский ресурс.

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

<Note>
  API-сервер Kubernetes удаляет события по истечении TTL — по умолчанию
  через один час (`--event-ttl`). Поэтому события — это краткоживущий сигнал о недавней активности,
  а не постоянный журнал аудита.
</Note>

<div id="viewing-events">
  ## Просмотр событий
</div>

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

```bash theme={null}
NS=<your-namespace>

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

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

```bash theme={null}
# 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`).

<div id="event-reasons">
  ## Справочник по причинам событий
</div>

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

<div id="resource-lifecycle">
  ### Жизненный цикл ресурсов
</div>

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

| Причина        | Тип     | Значение                                                                                                                                   |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `FailedCreate` | Warning | Оператору не удалось создать принадлежащий ему ресурс (например, StatefulSet, Service, ConfigMap, Secret, PodDisruptionBudget или задача). |
| `FailedUpdate` | Warning | Оператору не удалось обновить ресурс.                                                                                                      |
| `FailedDelete` | Warning | Оператору не удалось удалить принадлежащий ему ресурс в ходе реконсиляции или уменьшения масштаба.                                         |

<div id="cluster-readiness">
  ### Готовность кластера
</div>

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

| Причина           | Тип     | Значение                                                                                                                                                                                                            |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClusterReady`    | Normal  | Кластер стал готов: у каждого сегмента ClickHouse есть как минимум одна готовая реплика, либо кворум Keeper имеет лидера и достаточное количество ведомых узлов (или его единственная автономная реплика работает). |
| `ClusterNotReady` | Warning | Кластер вышел из состояния готовности — у сегмента ClickHouse не осталось ни одной готовой реплики, либо кворум Keeper потерял лидера или слишком много ведомых узлов.                                              |

<div id="scaling">
  ### Масштабирование
</div>

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

| Причина                    | Тип     | Значение                                                                                                                   |
| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `HorizontalScaleStarted`   | Normal  | Оператор начал добавлять или удалять реплики.                                                                              |
| `HorizontalScaleCompleted` | Normal  | Операция масштабирования завершена.                                                                                        |
| `ReplicaCreated`           | Normal  | Оператор добавил реплику в кластер.                                                                                        |
| `ReplicaDeleted`           | Normal  | Оператор удалил реплику при уменьшении числа реплик.                                                                       |
| `HorizontalScaleBlocked`   | Warning | Оператор отказался выполнять масштабирование, потому что текущее состояние Keeper пока не позволяет сделать это безопасно. |

<Note>
  `HorizontalScaleBlocked` — это событие, за которым стоит следить, если запрос на масштабирование Keeper, как кажется,
  ничего не даёт: оператор намеренно откладывает изменение и сохраняет текущий
  кворум, чтобы избежать split. В сообщении события указано ограничение,
  которое заблокировало изменение.
</Note>

<div id="external-secret">
  ### External secret
</div>

Генерируется для `ClickHouseCluster`, когда кластер ссылается на внешний Secret,
который оператор не может использовать. См. описание возможности External Secret в
[руководстве по настройке](/docs/ru/products/kubernetes-operator/guides/configuration).

| Причина                  | Тип     | Значение                                                                                               |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------ |
| `ExternalSecretNotFound` | Warning | Указанный Secret не существует в пространстве имен кластера.                                           |
| `ExternalSecretInvalid`  | Warning | Secret существует, но в нем отсутствуют обязательные ключи (сообщается только при политике `Observe`). |

<div id="version-checks">
  ### Проверки версий
</div>

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

| Причина                   | Тип     | Значение                                                                                                                                                                                                                         |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VersionProbeFailed`      | Warning | задача `version-probe` не смог определить версию запущенного ClickHouse.                                                                                                                                                         |
| `VersionDiverge`          | Warning | Обнаруженная версия реплики отличается от версии, которую оператор определил для кластера. Не выводится во время rolling updates.                                                                                                |
| `VersionUpgradeAvailable` | Warning | В настроенном канале обновления доступна более новая версия, запущенная версия отсутствует в этом канале или больше не поддерживается. Оператор никогда не выполняет обновление самостоятельно — это событие только информирует. |

<div id="clickhouse-warnings">
  ### Предупреждения сервера ClickHouse
</div>

| Причина             | Тип     | Значение                                                                                                      |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `ClickHouseWarning` | Warning | Предупреждение, о котором сообщает сам сервер ClickHouse и которое повторно публикуется из `system.warnings`. |

Эта последняя причина отличается: она не описывает действия самого оператора. На
каждой готовой реплике оператор периодически запрашивает таблицу
[`system.warnings`](https://clickhouse.com/docs/operations/system-tables/system_warnings) на сервере и
повторно публикует каждую строку как событие `Warning` в кластере, добавляя префикс
с именем реплики, из которой она получена. Так собственные предупреждения ClickHouse
о конфигурации и среде выполнения — устаревшие настройки, слишком низкие лимиты, небезопасные параметры — превращаются в события, которые можно увидеть
с помощью `kubectl`, не открывая сеанс `clickhouse-client` для каждой реплики.

```bash theme={null}
kubectl -n $NS get events \
  --field-selector reason=ClickHouseWarning,involvedObject.name=<name>
```

<div id="events-vs-metrics">
  ## События, метрики и состояния
</div>

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

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

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

<div id="troubleshooting">
  ## Устранение неполадок по событиям
</div>

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

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

<div id="related-guides">
  ## Связанные руководства
</div>

* [Мониторинг оператора](/docs/ru/products/kubernetes-operator/guides/monitoring) — метрики и проверки состояния, более устойчивый аналог событий.
* [Масштабирование](/docs/ru/products/kubernetes-operator/guides/scaling) — что защищает `HorizontalScaleBlocked` и как кворум Keeper ограничивает масштабирование.
* [Конфигурация](/docs/ru/products/kubernetes-operator/guides/configuration) — возможность External Secret, стоящая за событиями external-secret.