Eventos de Kubernetes

El operador registra eventos de Kubernetes en los objetos ClickHouseCluster y KeeperCluster que administra. Estos eventos muestran lo que hizo el operador durante la reconciliación — dónde fallaron los cambios en los recursos, cuándo un clúster pasó a estar listo, por qué se bloqueó el escalado — y sacan a la luz fallos que nunca llegan a un log que un usuario leería normalmente. Complementan las métricas al adjuntar un historial legible para humanos directamente al recurso personalizado.

clickhouse-controller informa eventos en los objetos ClickHouseCluster y keeper-controller los informa en los objetos KeeperCluster. Los eventos de fallo del ciclo de vida del recurso también hacen referencia al objeto dependiente correspondiente (un StatefulSet, Service, ConfigMap, Secret, PodDisruptionBudget, PersistentVolumeClaim o Job de comprobación de versión); otros eventos hacen referencia solo al clúster en sí.

La forma más rápida de verlos es con kubectl describe en el recurso personalizado, que muestra los eventos más recientes al final:

NS=<your-namespace>

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

Para ver los eventos directamente —por ejemplo, para observarlos en tiempo real o filtrarlos para ver solo los fallos— consulta el recurso events y filtra por el objeto implicado o por el tipo:

# 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

El controlador que lo reporta aparece en el origen del evento, por lo que puedes distinguir un evento de ClickHouseCluster (clickhouse-controller) de un evento de KeeperCluster (keeper-controller).

El operador emite un conjunto fijo de razones, agrupadas según lo que describen. Los eventos Normal indican el progreso esperado; los eventos Warning indican un fallo o un estado sobre el que el usuario debe actuar.

Se emite tanto en ClickHouseCluster como en KeeperCluster cuando el operador no puede aplicar un recurso gestionado por él durante la reconciliación.

Se emite en ambos tipos cuando el clúster cambia de estado de disponibilidad.

Se emite en KeeperCluster cuando el operador cambia la cantidad de réplicas.

Se emite en ClickHouseCluster cuando el clúster hace referencia a un Secret externo que el operador no puede usar. Consulta la función External Secret en la guía de configuración.

Emitidas por las comprobaciones de versión de ClickHouseCluster y KeeperCluster. VersionProbeFailed es específico del Job de sondeo de versión de ClickHouse, version-probe.

Esta última razón es distinta: no describe las acciones del propio operador. En cada réplica lista, el operador consulta periódicamente la tabla system.warnings del servidor y republica cada fila como un evento Warning en el clúster, con el prefijo de la réplica de la que procede. Esto convierte las propias advertencias de configuración y de ejecución de ClickHouse —ajustes obsoletos, límites bajos, opciones inseguras— en eventos que puedes ver con kubectl sin abrir una sesión de clickhouse-client en cada réplica.

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

El operador expone tres superficies de observabilidad; usa cada una para lo que mejor sabe hacer:

• Eventos (esta guía) — recientes, legibles para humanos, asociados al objeto. Ideales para "qué acaba de pasarle a este clúster" y para la resolución interactiva de problemas con kubectl describe. Caducan.
• status.conditions en el recurso personalizado — la verdad actual y persistente (Ready, External Secret válido, escalado permitido, versión sincronizada). Lo mejor para scripts y compuertas de estado de GitOps. Léalas con kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'.
• Métricas — duraderas y numéricas. Ideales para dashboards y para generar alertas ante una tasa sostenida de errores de reconciliación.

Un evento Warning y una condición False a menudo describen el mismo problema desde dos ángulos: el evento captura el momento y el mensaje; la condición refleja el estado hasta que se despeja.

Algunas señales habituales y lo que suelen indicar:

• FailedCreate / FailedUpdate repetidos — el operador no puede aplicar un recurso. El mensaje del evento incluye el error de la API (rechazo en admisión, cuota, spec no válida). La reconciliación vuelve a intentarlo, así que una causa transitoria se resuelve sola; una persistente requiere corregir la spec o el clúster.
• ClusterNotReady sin un ClusterReady correspondiente — el clúster no se está recuperando. El mensaje del evento indica qué segmentos no están listos o cuál es el problema de cuórum; compruebe los pods que hay detrás de ellos.
• HorizontalScaleBlocked — un escalado previsto se está reteniendo por seguridad. Lea el mensaje para conocer la restricción exacta antes de forzar nada.
• ExternalSecretNotFound / ExternalSecretInvalid — corrija el nombre del Secret o sus claves; la condición ExternalSecretValid correspondiente cambia a True una vez que el operador puede usarlo.
• ClickHouseWarning — el problema está dentro de ClickHouse, no en el operador. Trate el mensaje como trataría una fila de system.warnings.

• Monitoreo del operador — métricas y sondas de estado, la contraparte persistente de los eventos.
• Escalado — qué protege HorizontalScaleBlocked y cómo el quórum de Keeper limita el escalado.
• Configuración — la funcionalidad External Secret detrás de los eventos de external-secret.