Eventos do Kubernetes

O operador registra eventos do Kubernetes nos objetos ClickHouseCluster e KeeperCluster que gerencia. Esses eventos mostram o que o operador fez durante a reconciliação — onde mudanças em recursos falharam, quando um cluster ficou pronto, por que o escalonamento foi bloqueado — e revelam falhas que nunca chegam a aparecer em logs que os usuários normalmente consultam. Eles complementam as métricas ao anexar um histórico legível por humanos diretamente ao recurso personalizado.

O clickhouse-controller relata eventos em objetos ClickHouseCluster, e o keeper-controller os relata em objetos KeeperCluster. Os eventos de falha no ciclo de vida do recurso também fazem referência ao objeto associado a eles (um StatefulSet, Service, ConfigMap, Secret, PodDisruptionBudget, PersistentVolumeClaim ou version-probe Job); os demais eventos fazem referência apenas ao próprio cluster.

A maneira mais rápida de ver isso é usar kubectl describe no recurso personalizado, que lista os eventos mais recentes na parte inferior:

NS=<your-namespace>

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

Para listar eventos diretamente — por exemplo, para acompanhá-los em tempo real ou filtrar para ver apenas falhas — consulte o recurso events e filtre pelo objeto envolvido ou pelo 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

O controlador emissor aparece na origem do evento, para que você possa distinguir um evento ClickHouseCluster (clickhouse-controller) de um evento KeeperCluster (keeper-controller).

O operador emite um conjunto fixo de motivos, agrupados de acordo com o que descrevem. Eventos Normal indicam o progresso esperado; eventos Warning indicam uma falha ou um estado que exige ação do usuário.

Emitido em ClickHouseCluster e KeeperCluster quando o operador não consegue aplicar um recurso gerenciado durante a reconciliação.

Emitido para ambos os tipos quando o cluster cruza o limite de prontidão.

Emitido em KeeperCluster quando o operador altera o número de réplicas.

Emitido em ClickHouseCluster quando o cluster referencia um Secret externo que o operador não consegue usar. Consulte o recurso Secret externo no guia de configuração.

Emitidos pelas verificações de versão de ClickHouseCluster e KeeperCluster. VersionProbeFailed é específico do Job version-probe do ClickHouse.

Esse último Reason é diferente: ele não descreve as ações do próprio operador. Em cada réplica pronta, o operador consulta periodicamente a table system.warnings do servidor e republica cada linha como um evento Warning no cluster, com o prefixo da réplica de onde veio. Isso transforma os próprios avisos de configuração e de runtime do ClickHouse — configurações obsoletas, limites baixos, opções inseguras — em eventos que você pode ver com kubectl sem abrir uma sessão clickhouse-client em cada réplica.

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

O operador expõe três superfícies de observabilidade; use cada uma naquilo em que ela é melhor:

• Eventos (este guia) — recentes, legíveis por humanos, vinculados ao objeto. Melhores para "o que acabou de acontecer com este cluster" e para troubleshooting interativo com kubectl describe. Eles expiram.
• status.conditions no recurso personalizado — a verdade atual e persistente (pronto, Secret externo válido, escalonamento permitido, versão sincronizada). Melhor para scripts e verificações de integridade do GitOps. Leia com kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'.
• Métricas — duráveis e numéricas. Melhores para dashboards e para alertar sobre uma taxa sustentada de erros de reconciliação.

Um evento Warning e uma condição False frequentemente descrevem o mesmo problema por dois ângulos: o evento registra o momento e a mensagem, e a condição reflete o estado até que seja normalizado.

Alguns sinais comuns e o que eles indicam:

• FailedCreate / FailedUpdate se repetindo — o operador não consegue aplicar um recurso. A mensagem do evento traz o erro da API (rejeição no admission, quota, spec inválida). A reconciliação faz novas tentativas, então uma causa transitória se resolve sozinha; uma causa persistente exige corrigir a spec ou o cluster.
• ClusterNotReady sem um ClusterReady correspondente — o cluster não está se recuperando. A mensagem do evento informa quais shards não estão prontos ou qual é o problema de quórum; verifique os pods por trás deles.
• HorizontalScaleBlocked — uma escala pretendida está sendo bloqueada por segurança. Leia a mensagem para ver a restrição exata antes de forçar qualquer coisa.
• ExternalSecretNotFound / ExternalSecretInvalid — corrija o nome do Secret ou suas chaves; a condição ExternalSecretValid correspondente muda para True assim que o operador conseguir usá-lo.
• ClickHouseWarning — o problema está no ClickHouse, não no operador. Trate a mensagem como trataria uma linha de system.warnings.

• Monitoramento do operador — métricas e probes de integridade, o equivalente persistente aos eventos.
• Escalonamento — o que HorizontalScaleBlocked protege e como os limites de quórum do Keeper restringem o escalonamento.
• Configuração — o recurso Secret externo por trás dos eventos external-secret.