Kubernetes イベント

オペレーター は、管理している ClickHouseCluster および KeeperCluster オブジェクトに Kubernetes イベントを記録します。これらのイベントは、オペレーター が リコンサイル中に何を行ったのかをたどれるようにするものです。たとえば、どこでリソース変更に失敗したか、 いつクラスターが Ready になったか、なぜスケーリングがブロックされたかを示し、 通常ユーザーが目にする Log には出てこない障害も可視化します。さらに、 カスタムリソースに人間が読みやすい履歴を直接紐付けることで、 メトリクス を補完します。

clickhouse-controller は ClickHouseCluster オブジェクトにイベントを報告し、keeper-controller は KeeperCluster オブジェクトにイベントを報告します。リソースの ライフサイクルに関する失敗イベントには、対象となる管理下のオブジェクト ( StatefulSet、Service、ConfigMap、Secret、PodDisruptionBudget、 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) を見分けることができます。

オペレーターは、説明対象ごとにグループ化された固定の理由セットを出力します。Normal イベントは想定どおりの進行を示し、Warning イベントは障害またはユーザーによる対処が必要な状態を示します。

オペレーターがリコンサイル中に管理対象リソースの適用に失敗した場合、ClickHouseCluster と KeeperCluster の両方で発生します。

クラスターが準備状態のしきい値をまたいだときに、両方の Kind で発行されます。

オペレーターがレプリカ数を変更すると、KeeperCluster で発生します。

クラスターが、オペレーターで使用できない外部 Secret を参照している場合に、ClickHouseCluster で発行されます。External Secret 機能については、設定ガイドを参照してください。

ClickHouseCluster と KeeperCluster のバージョンチェックによって発行されます。 VersionProbeFailed は、ClickHouse の version-probe Job 固有のイベントです。

この最後の Reason は性質が異なり、オペレーター 自身の操作を示すものではありません。各準備完了状態の レプリカで、オペレーター はサーバーの system.warnings テーブルを定期的に照会し、 各行を、どのレプリカ由来かを示すプレフィックス付きで、クラスター上の Warning イベントとして再公開します。これにより、ClickHouse 自身の構成や実行時に関する警告 — 廃止された設定、低すぎる制限値、安全でないオプション — を、各レプリカに対して clickhouse-client セッションを開かなくても、kubectl で確認できるようになります。

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

オペレーターは、オブザーバビリティのための 3 つの手段を提供します。それぞれを最適な用途で使い分けてください。

• 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 名またはそのキーを修正してください。オペレーターがそれを使用できるようになると、対応する ExternalSecretValid condition は True に変わります。
• ClickHouseWarning — 問題はオペレーターではなく ClickHouse 内にあります。メッセージは system.warnings の行と同様に扱ってください。

• オペレーターの監視 — メトリクスとヘルスプローブ。イベントを補完する、継続的に確認できる情報です。
• スケーリング — HorizontalScaleBlocked が何を保護し、Keeper のクォーラムがどのようにスケーリングを制約するのかを説明します。
• 設定 — external-secret イベントの背後にある External Secret 機能。