ClickHouseCluster および
KeeperCluster オブジェクトに Kubernetes イベントを記録します。これらのイベントは、オペレーター が
リコンサイル中に何を行ったのかをたどれるようにするものです。たとえば、どこでリソース変更に失敗したか、
いつクラスターが Ready になったか、なぜスケーリングがブロックされたかを示し、
通常ユーザーが目にする Log には出てこない障害も可視化します。さらに、
カスタムリソースに人間が読みやすい履歴を直接紐付けることで、
メトリクス
を補完します。
clickhouse-controller は ClickHouseCluster オブジェクトにイベントを報告し、keeper-controller は
KeeperCluster オブジェクトにイベントを報告します。リソースの
ライフサイクルに関する失敗イベントには、対象となる管理下のオブジェクト (
StatefulSet、Service、ConfigMap、Secret、PodDisruptionBudget、
PersistentVolumeClaim、または version-probe Job) への参照も含まれます。
それ以外のイベントは、クラスター自体のみを参照します。
Kubernetes API server では、イベントは有効期限 (TTL) の経過後に失効します。デフォルトは
1 時間です
(
--event-ttl)。そのため、イベントは直近のアクティビティを示す一時的なシグナルであり、
永続的な監査証跡ではありません。イベントの確認
kubectl describe を実行することです。最新のイベントが末尾に表示されます。
events リソースにクエリを実行し、対象オブジェクトまたはタイプで絞り込みます:
ClickHouseCluster のイベント (clickhouse-controller) と KeeperCluster のイベント
(keeper-controller) を見分けることができます。
イベント理由のリファレンス
Normal
イベントは想定どおりの進行を示し、Warning イベントは障害またはユーザーによる対処が必要な状態を示します。
リソースのライフサイクル
ClickHouseCluster と KeeperCluster の両方で発生します。
クラスターの準備状態
スケーリング
KeeperCluster で発生します。
HorizontalScaleBlocked は、Keeper のスケール リクエストを行っても
何も起きないように見えるときに確認すべきイベントです。分割のリスクを
避けるため、オペレーターは意図的に変更を保留し、既存の
クォーラムを維持します。イベントメッセージには、
変更を妨げた制約が記載されます。External Secret
ClickHouseCluster で発行されます。External Secret 機能については、設定ガイドを参照してください。
バージョンチェック
ClickHouseCluster と KeeperCluster のバージョンチェックによって発行されます。
VersionProbeFailed は、ClickHouse の version-probe Job 固有のイベントです。
ClickHouse server の警告
この最後の Reason は性質が異なり、オペレーター 自身の操作を示すものではありません。各準備完了状態の
レプリカで、オペレーター はサーバーの
system.warnings テーブルを定期的に照会し、
各行を、どのレプリカ由来かを示すプレフィックス付きで、クラスター上の Warning イベントとして再公開します。これにより、ClickHouse
自身の構成や実行時に関する警告 — 廃止された設定、低すぎる制限値、安全でないオプション —
を、各レプリカに対して clickhouse-client セッションを開かなくても、kubectl で確認できるようになります。
イベント、メトリクス、条件
- Events (このガイド) — 直近の出来事を人が読める形で示し、オブジェクトに関連付けられます。
「このクラスターで今何が起きたか」の把握や、
kubectl describeを使った対話的なトラブルシューティングに最適です。 一定時間で失効します。 - カスタムリソース上の
status.conditions— 現在の永続的な状態を示す信頼できる情報です (ready、external secret valid、scale allowed、version in sync) 。 スクリプトや GitOps のヘルスゲートに最適です。以下で確認できます。kubectl get clickhousecluster <name> -o jsonpath='{.status.conditions}'. - Metrics — 永続的な数値データです。 ダッシュボードや、継続的なリコンサイルエラー率に対するアラートに最適です。
Warning イベントと False condition は、同じ問題を 2 つの側面から表していることがよくあります。イベントは発生した瞬間とメッセージを捉え、condition は解消されるまでその状態を反映します。
イベントを使ったトラブルシューティング
FailedCreate/FailedUpdateが繰り返し発生する — オペレーターがリソースを適用できていません。イベントメッセージには API エラー (admission による拒否、クォータ、無効な spec) が含まれます。リコンサイルでは再試行が行われるため、一時的な原因であれば自然に解消しますが、継続する場合は spec またはクラスター側の修正が必要です。- 対応する
ClusterReadyを伴わないClusterNotReady— クラスターが復旧できていません。イベントメッセージには、Ready でない分片、またはクォーラムの問題が示されます。該当するポッドを確認してください。 HorizontalScaleBlocked— 想定されたスケール変更が、安全のため保留されています。何かを強制する前に、まずメッセージで正確な制約内容を確認してください。ExternalSecretNotFound/ExternalSecretInvalid— Secret 名またはそのキーを修正してください。オペレーターがそれを使用できるようになると、対応するExternalSecretValidcondition はTrueに変わります。ClickHouseWarning— 問題はオペレーターではなく ClickHouse 内にあります。メッセージはsystem.warningsの行と同様に扱ってください。