Événements Kubernetes

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 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 :

NS=<your-namespace>

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

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 :

# 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

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).

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.

É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.

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

Émis pour KeeperCluster lorsque l’opérateur modifie le nombre de répliques.

É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.

Émis par les vérifications de version pour ClickHouseCluster et KeeperCluster. VersionProbeFailed est spécifique au Job version-probe de 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.

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

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.

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.