Skip to main content
L’opérateur enregistre des événements Kubernetes sur les objets ClickHouseCluster et KeeperCluster qu’il gère. Ces événements retracent ce que l’opérateur a fait pendant la réconciliation — à quel endroit les modifications de ressources ont échoué, quand un cluster est devenu prêt, pourquoi la mise à l’échelle a été bloquée — et font remonter des échecs qui n’apparaissent jamais dans les journaux qu’un utilisateur consulte habituellement. Ils complètent les métriques en associant un historique lisible directement à la ressource personnalisée. Le clickhouse-controller signale des événements sur les objets ClickHouseCluster et le keeper-controller les signale sur les objets KeeperCluster. Les événements d’échec du cycle de vie des ressources référencent également l’objet géré concerné (un StatefulSet, Service, ConfigMap, Secret, PodDisruptionBudget, PersistentVolumeClaim ou Job version-probe) ; les autres événements ne référencent que le cluster lui-même.
Le serveur d’API Kubernetes supprime les événements après un TTL — une heure par défaut (--event-ttl). Les événements constituent donc un signal de courte durée sur l’activité récente, et non une piste d’audit durable.

​
Consulter les événements

Le moyen le plus rapide est d’exécuter kubectl describe sur la ressource personnalisée, ce qui affiche les événements les plus récents en bas :
Pour lister directement les événements — par exemple pour les suivre en direct ou n’afficher que les échecs — interrogez la ressource events et filtrez selon l’objet impliqué ou le type :
Le contrôleur à l’origine du rapport apparaît dans la source de l’événement, ce qui vous permet de distinguer un événement ClickHouseCluster (clickhouse-controller) d’un événement KeeperCluster (keeper-controller).

​
Référence des raisons d’événement

L’opérateur émet un ensemble fixe de raisons, regroupées selon ce qu’elles décrivent. Les événements Normal indiquent une progression attendue ; les événements Warning signalent une défaillance ou un état nécessitant une intervention de l’utilisateur.

​
Cycle de vie des ressources

Émis pour ClickHouseCluster et KeeperCluster lorsque l’opérateur ne parvient pas à appliquer une ressource dont il est propriétaire lors de la réconciliation.

​
Disponibilité du cluster

Émis pour les deux types lorsque le cluster change d’état de disponibilité.

​
Mise à l’échelle

Émis pour KeeperCluster lorsque l’opérateur modifie le nombre de répliques.
HorizontalScaleBlocked est l’événement à surveiller lorsqu’une demande de mise à l’échelle de Keeper semble rester sans effet : l’opérateur suspend délibérément la modification et conserve le quorum existant plutôt que de risquer un split. Le message de l’événement indique la contrainte qui a bloqué la modification.

​
Secret externe

Émis pour ClickHouseCluster lorsque le cluster fait référence à un Secret externe que l’opérateur ne peut pas utiliser. Consultez la fonctionnalité External Secret dans le guide de configuration.

​
Vérifications de version

Émis par les vérifications de version pour ClickHouseCluster et KeeperCluster. VersionProbeFailed est spécifique au Job version-probe de ClickHouse.

​
Avertissements du serveur ClickHouse

Cette dernière raison est particulière : elle ne décrit pas les actions de l’opérateur lui-même. Sur chaque réplique en état Ready, l’opérateur interroge périodiquement la table system.warnings du serveur et republie chaque ligne sous forme d’événement Warning sur le cluster, préfixé par la réplique dont elle provient. Cela transforme les avertissements natifs de configuration et d’exécution de ClickHouse — paramètres obsolètes, limites trop basses, options non sûres — en événements visibles avec kubectl, sans avoir à ouvrir une session clickhouse-client sur chaque réplique.

​
Événements, métriques et conditions

L’opérateur expose trois surfaces d’observabilité ; utilisez chacune selon ce qu’elle fait le mieux :
  • Événements (ce guide) — récents, lisibles par des humains, rattachés à l’objet. À privilégier pour « ce qui vient d’arriver à ce cluster » et le dépannage interactif avec kubectl describe. Ils expirent.
  • status.conditions sur la ressource personnalisée — l’état réel, actuel et persistant (prêt, secret externe valide, mise à l’échelle autorisée, version synchronisée). À privilégier pour les scripts et les contrôles d’état de santé GitOps. Consultez-les avec kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'.
  • Métriques — pérennes et numériques. À privilégier pour les tableaux de bord et pour déclencher des alertes sur un taux soutenu d’erreurs de réconciliation.
Un événement Warning et une condition False décrivent souvent le même problème sous deux angles : l’événement capture le moment et le message, la condition reflète l’état jusqu’à sa résolution.

​
Dépannage avec les événements

Quelques signaux courants et ce qu’ils indiquent :
  • FailedCreate / FailedUpdate répétés — l’opérateur ne peut pas appliquer une ressource. Le message de l’événement contient l’erreur d’API (rejet à l’admission, quota, spécification non valide). La réconciliation effectue de nouvelles tentatives, donc une cause transitoire se résout d’elle-même ; une cause persistante nécessite une correction de la spécification ou du cluster.
  • ClusterNotReady sans ClusterReady correspondant — le cluster ne se rétablit pas. Le message de l’événement indique les shards non prêts ou le problème de quorum ; vérifiez les pods concernés.
  • HorizontalScaleBlocked — une mise à l’échelle prévue est bloquée par sécurité. Lisez le message pour connaître la contrainte exacte avant de forcer quoi que ce soit.
  • ExternalSecretNotFound / ExternalSecretInvalid — corrigez le nom du Secret ou ses clés ; la condition ExternalSecretValid correspondante passe à True une fois que l’opérateur peut l’utiliser.
  • ClickHouseWarning — le problème se situe dans ClickHouse, pas dans l’opérateur. Traitez le message comme vous le feriez pour une ligne de system.warnings.
  • Surveillance de l’opérateur — métriques et probes de santé, la contrepartie persistante des événements.
  • Mise à l’échelle — ce que protège HorizontalScaleBlocked et comment le quorum de Keeper limite la mise à l’échelle.
  • Configuration — la fonctionnalité External Secret qui sous-tend les événements external-secret.
Dernière modification le 23 juillet 2026