Skip to main content
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.
O servidor da API do Kubernetes expira eventos após um TTL — uma hora por padrão (--event-ttl). Portanto, os eventos são um sinal de curta duração da atividade recente, não uma trilha de auditoria persistente.

​
Visualizando eventos

A maneira mais rápida de ver isso é usar kubectl describe no recurso personalizado, que lista os eventos mais recentes na parte inferior:
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:
O controlador emissor aparece na origem do evento, para que você possa distinguir um evento ClickHouseCluster (clickhouse-controller) de um evento KeeperCluster (keeper-controller).

​
Referência dos motivos de evento

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.

​
Ciclo de vida do recurso

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

​
Prontidão do cluster

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

​
Escalonamento

Emitido em KeeperCluster quando o operador altera o número de réplicas.
HorizontalScaleBlocked é o evento a observar quando uma solicitação de escalonamento do Keeper parece não surtir efeito: o operador retém deliberadamente a alteração e mantém o quórum existente em vez de correr o risco de uma divisão. A mensagem do evento informa a condição que bloqueou a alteração.

​
Secret externo

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.

​
Verificações de versão

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

​
Avisos do servidor 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.

​
Eventos, métricas e condições

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.

​
Solução de problemas com eventos

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.
Última modificação em 23 de julho de 2026