Kubernetes 이벤트

operator는 관리 중인 ClickHouseCluster 및 KeeperCluster 객체에 Kubernetes 이벤트를 기록합니다. 이러한 이벤트는 operator가 리컨실리에이션 과정에서 수행한 작업을 보여줍니다. 즉, 리소스 변경이 어디에서 실패했는지, 클러스터가 언제 준비 상태가 되었는지, 왜 스케일링이 차단되었는지 등을 추적할 수 있으며, 사용자가 일반적으로 확인하는 로그에는 남지 않는 실패도 드러냅니다. 또한 메트릭을 보완하여, 사람이 읽을 수 있는 이력을 사용자 지정 리소스에 직접 연결합니다.

clickhouse-controller는 ClickHouseCluster 객체에 이벤트를 보고하고, keeper-controller는 KeeperCluster 객체에 이벤트를 보고합니다. 리소스 수명 주기 실패 이벤트에는 해당 이벤트와 관련된 소유 객체도 함께 참조됩니다(예: StatefulSet, Service, ConfigMap, 시크릿, 파드 중단 예산, PersistentVolumeClaim 또는 version-probe Job). 그 외 이벤트는 클러스터 자체만 참조합니다.

가장 빠르게 확인하는 방법은 사용자 지정 리소스에 대해 kubectl describe를 실행하는 것이며, 그러면 하단에 가장 최근의 이벤트가 표시됩니다:

NS=<your-namespace>

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

이벤트를 직접 나열하려면 — 예를 들어 실시간으로 확인하거나 실패한 항목만 필터링하려는 경우 — events 리소스에 쿼리를 실행한 다음 관련 객체 또는 유형으로 필터링합니다:

# 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

이벤트 소스에 보고 컨트롤러가 표시되므로, ClickHouseCluster 이벤트(clickhouse-controller)와 KeeperCluster 이벤트 (keeper-controller)를 구분할 수 있습니다.

연산자는 설명하는 내용에 따라 분류된 고정된 Reason 집합을 발생시킵니다. Normal 이벤트는 예상된 진행 상황을 나타내고, Warning 이벤트는 실패 또는 사용자가 조치해야 하는 상태를 나타냅니다.

리컨실리에이션 중 오퍼레이터가 자신이 관리하는 리소스를 적용하지 못하면 ClickHouseCluster와 KeeperCluster 모두에서 이 이벤트가 발생합니다.

클러스터가 준비 상태 경계를 넘을 때 두 Kind 모두에서 발생합니다.

오퍼레이터가 레플리카 수를 변경할 때 KeeperCluster에서 발생하는 이벤트입니다.

클러스터가 오퍼레이터에서 사용할 수 없는 외부 시크릿을 참조할 때 ClickHouseCluster에 대해 이 이벤트가 발생합니다. 자세한 내용은 구성 가이드의 External Secret 기능을 참조하십시오.

ClickHouseCluster 및 KeeperCluster의 버전 확인에서 발생합니다. VersionProbeFailed는 ClickHouse 버전 프로브 Job에만 해당합니다.

마지막 Reason은 성격이 다릅니다. 이는 오퍼레이터 자체의 동작을 설명하는 것이 아닙니다. 각 준비된 레플리카에서 오퍼레이터는 주기적으로 서버의 system.warnings 테이블을 조회하고, 각 행을 해당 행이 나온 레플리카 이름을 접두사로 붙여 클러스터의 Warning 이벤트로 다시 게시합니다. 이렇게 하면 ClickHouse 자체의 구성 및 런타임 경고(더 이상 사용되지 않는 설정, 낮은 제한값, 안전하지 않은 옵션)를 각 레플리카에 대해 clickhouse-client 세션을 열지 않고도 kubectl로 확인할 수 있는 이벤트로 바꿀 수 있습니다.

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

연산자는 관측성을 위해 3가지 수단을 제공합니다. 각각 가장 적합한 용도에 맞게 사용하십시오:

• 이벤트 (이 가이드) — 최근에 발생한 내용으로, 사람이 읽기 쉽고 객체에 연결되어 있습니다. "이 클러스터에서 방금 무슨 일이 있었는지"를 파악하고 kubectl describe로 대화형 문제 해결을 수행하는 데 가장 적합합니다. 시간이 지나면 만료됩니다.
• 사용자 지정 리소스의 status.conditions — 현재 상태에 대한 지속적인 단일 진실 소스입니다 (준비 완료, 외부 시크릿 유효, 스케일 허용, 버전 동기화). 스크립트와 GitOps 헬스 게이트에 가장 적합합니다. 다음 명령으로 확인하십시오: kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'.
• 메트릭 — 지속적으로 유지되며 수치로 표현됩니다. 대시보드와 reconcile 오류율이 지속될 때 알림을 설정하는 데 가장 적합합니다.

Warning 이벤트와 False 조건은 같은 문제를 서로 다른 두 관점에서 설명하는 경우가 많습니다. 이벤트는 발생 시점과 메시지를 포착하고, 조건은 해소될 때까지 해당 상태를 반영합니다.

몇 가지 일반적인 신호와 그 의미는 다음과 같습니다.

• FailedCreate / FailedUpdate 반복 — 연산자가 리소스를 적용하지 못하고 있습니다. 이벤트 메시지에는 API 오류(admission 거부, 할당량, 잘못된 spec)가 포함됩니다. 리컨실리에이션은 재시도되므로 일시적인 원인은 저절로 해소되지만, 지속되는 원인은 spec 또는 클러스터를 수정해야 합니다.
• 이에 대응하는 ClusterReady 없이 ClusterNotReady가 발생 — 클러스터가 복구되지 못하고 있습니다. 이벤트 메시지에는 준비되지 않은 세그먼트나 quorum 문제가 명시되므로, 해당 파드를 확인하십시오.
• HorizontalScaleBlocked — 의도한 수평 확장/축소가 안전을 위해 보류된 상태입니다. 강제로 진행하기 전에 정확한 제약 사항을 메시지에서 확인하십시오.
• ExternalSecretNotFound / ExternalSecretInvalid — 시크릿 이름 또는 그 안의 키를 수정하십시오. 연산자가 이를 사용할 수 있게 되면 해당 ExternalSecretValid 조건이 True로 바뀝니다.
• ClickHouseWarning — 문제는 연산자가 아니라 ClickHouse 내부에 있습니다. 메시지는 system.warnings의 행을 보듯이 해석하십시오.

• operator 모니터링 — 메트릭과 상태 프로브로, 이벤트와 달리 지속적으로 확인할 수 있는 신호입니다.
• 스케일링 — HorizontalScaleBlocked가 무엇을 보호하는지, 그리고 Keeper quorum이 스케일링을 어떻게 제한하는지 설명합니다.
• 구성 — external-secret 이벤트의 기반이 되는 External Secret 기능입니다.