huawei-cloud-cce-kubernetes-event-analyzer

Huawei Cloud CCE Kubernetes Event Analyzer

概要

Huawei Cloud CCE クラスター内の Kubernetes イベントを照会・分析し、警告、繰り返し発生する失敗パターン、影響を受けるリソース、有用な診断への引き継ぎ情報を特定します。このスキルは、kubectl による現在のイベント表示と、LTS による過去のイベント表示に対応しています。

アーキテクチャ：python3 scripts/huawei-cloud.py ディスパッチャー -> 外部 kubeconfig 経由の kubectl または現在のイベント用の kubectl cce／履歴イベント用の kubectl cce による LogConfig の検出と hcloud LTS ListLogs -> フィルタリングとグループ化 -> 診断への引き継ぎ。

実行方法：同梱のディスパッチャーのみを呼び出してください。Python Kubernetes SDK の生の呼び出し、Kubernetes API の直接呼び出し、場当たり的なクラウドコマンドで Kubernetes イベントを照会しないでください。huawei_get_cce_events の実装は内部で kubectl を呼び出します。まず外部 kubeconfig によるアクセスを試し、次に kubectl cce プラグインにフォールバックします。

関連スキル：

• huawei-cloud-kubectl-cce-installer - クラスターへのアクセスに必要な kubectl と kubectl-cce プラグインをインストールします
• huawei-cloud-cce-metric-analyzer - CCE とクラウドリソースのメトリクス

機能：

• クラスター全体または名前空間内の Kubernetes イベントを照会します
• 外部 kubectl kubeconfig アクセスまたは kubectl cce を通じてイベントを読み取ります
• 明示的な時間範囲内の過去のイベントレコードを LTS から照会します
• 種類、理由、名前空間、リソース、タイムスタンプでイベントをフィルタリングしてグループ化します
• イベントが参照する、対応対象リソースの現在の状態を確認します
• 指定された現在または過去のイベント結果を、クラウドへの追加リクエストなしでローカル分析します
• 繰り返し発生する警告パターンを特定し、診断スキルに根拠を引き継ぎます

一般的な使用例：

• 「この CCE クラスターの Warning イベントを一覧表示して」
• 「default 名前空間で繰り返し発生する FailedScheduling イベントを見つけて」
• 「LTS から過去の ImagePullBackOff イベントを照会して」
• 「インシデント中に頻発した Kubernetes イベントの理由を分析して」

前提条件

1. ランタイム依存関係

• ディスパッチャーと結果処理用の Python 3.8 以降
• クラスターの検索と一時的な外部 kubeconfig の生成用の hcloud（KooCLI）
• 現在のイベントを読み取るための kubectl
• クラスターに使用可能な外部エンドポイントがない場合は kubectl-cce。詳しくは kubectl-cce.md を参照してください
• hcloud の LTS コマンドサポート、および Cloud Native Log Collection アドオン（log-agent）と default-event のイベントから LTS への LogConfig。huawei_query_k8s_events_from_lts は kubectl cce を通じて logconfigs.logging.openvessel.io を読み取り、設定された LTS ID を使って hcloud LTS ListLogs を呼び出します。

2. 認証情報の設定

• 外部 kubeconfig アクセスでは、hcloud 認証情報の優先順位は、ツールの明示的なパラメーター > ローカル hcloud プロファイル > 環境変数です。
• kubectl cce へのフォールバックでは、ツールの明示的なパラメーターまたは環境変数から AK/SK と対象クラスターの project_id が必要です。暗号化された hcloud プロファイルの認証情報はプラグインで再利用できません。project_id がある場合、実装は kubectl cce --project-id <project-id> として明示的に渡します。
• LTS の照会には、有効な Huawei Cloud 認証情報と認可されたプロジェクトが必要です。

セキュリティルール：

• AK/SK、セキュリティトークン、kubeconfig の内容、一時的なクライアント認証情報を表示、保存、ハードコードしないでください。
• 認証情報を確認するために echo $HUAWEI_AK または echo $HUAWEI_SK を使用しないでください。
• 外部 kubeconfig アクセスには、ローカル hcloud プロファイルを優先してください。
• 最小権限の IAM ID と読み取り専用の Kubernetes RBAC 権限を使用してください。

任意の環境変数フォールバック：

export HUAWEI_AK=<your-ak>
export HUAWEI_SK=<your-sk>
export HUAWEI_REGION=cn-north-4
export HUAWEI_PROJECT_ID=<project-id>
export HUAWEI_SECURITY_TOKEN=<security-token>

3. IAM 権限要件

権限	目的
cce:cluster:get	クラスターの外部エンドポイントが利用可能か確認します
cce:cluster:createCert	外部からの kubectl アクセス用に一時的な kubeconfig を生成します
lts:logs:search	LTS 内の過去のイベントレコードをクエリします

有効な Kubernetes ID には、対象の名前空間またはクラスター内のイベントに対する読み取り専用の get および list 権限も必要です。

権限エラーへの対応：

1. 失敗した操作と必要な権限を報告します。
2. 不足している IAM または Kubernetes RBAC 権限を付与するようユーザーに依頼します。
3. ユーザーが権限の準備完了を確認するまで、再試行しないでください。

コアコマンド

すべてのコマンドで、同梱のディスパッチャーを使用します。

python3 scripts/huawei-cloud.py <tool-name> key=value key=value

KooCLI コマンド形式の標準

ユーザーは生の hcloud コマンドではなく、ディスパッチャーを呼び出します。現在のイベントをクエリする際、ディスパッチャーは必要に応じて、CCE クラスターの確認と一時的な外部 kubeconfig の生成にのみ hcloud を内部で使用します。

python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

次のルールに従ってください。

• key=value 形式のパラメーターを使用し、スペースや特殊なシェル文字を含む値は引用符で囲みます。
• 認証情報、セキュリティトークン、一時的な kubeconfig ファイルを表示または保存しないでください。
• クラスターを対象とするクエリでは、正確な cluster_id の値を使用します。
• LTS クエリには、start_time と end_time の両方を指定して時間範囲を設定します。

1. 現在の Kubernetes イベント

# Query Warning Events (default)
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

# Query Events in a namespace
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> namespace=default

# Limit returned Event records
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> limit=100

# Query all Event types only when explicitly needed
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> event_type=all limit=100

このツールは、Kubernetes API のサーバー側フィールドセレクターを使用し、デフォルトでは Warning イベントのみを返します。最初に一時的な kubeconfig を使って外部エンドポイントにアクセスし、その後、kubectl cce にフォールバックします。大規模なクラスターでは、すべてのイベント履歴を取得すると結果が膨大になる可能性があります。ユーザーが event_type=all を明示的にリクエストした場合にのみ、すべてのタイプをクエリしてください。

2. LTS から過去のイベントを取得する

# Query an explicit historical window
python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 06:00:00" \
  end_time="2026-05-30 08:00:00"

# Query with an LTS keyword filter
python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 00:00:00" \
  end_time="2026-05-30 23:59:59" \
  keywords=FailedScheduling

LTS の時刻形式は UTC の YYYY-MM-DD HH:MM:SS です。このツールは入力値を常に UTC として解釈し、ホストのローカルタイムゾーンとしては解釈しません。クラスターには、Cloud Native Log Collection アドオン（log-agent）がインストールされて正常に動作しており、default-event Event-to-LTS LogConfig が設定されている必要があります。このツールは kubectl cce --cluster-id <cluster-id> --region <region> get logconfigs.logging.openvessel.io -A -o json を使用し、default-event を選択して、outputDetail.LTS.ltsGroupID と ltsStreamID を読み取ります。LTS クエリはデフォルトで event_type=Warning を使用し、サーバー側のキーワードフィルターとして Warning を指定します。大規模なクラスターでは、ユーザーの確認後にのみ event_type=all を指定してすべてのイベント履歴をリクエストしてください。この指定により、タイプのキーワードフィルターが削除されます。LTS のフィルタリングはキーワードマッチングであり、構造化フィールドセレクターではありません。

3. イベント結果のクエリと分析

events を指定しない場合、このツールはデフォルトで現在のクラスターイベントをクエリして分析します。1 時間を超える過去の期間を対象とするリクエストでは、時間範囲を設定して LTS を使用してください。start_time または end_time を指定すると、自動的に LTS が選択されます。event_source=lts を明示的に設定することもできます。events 配列（または events を含む完全なレスポンスオブジェクト）を渡すと、オフライン分析の動作が維持されます。

# Query and analyze current Events
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

# Query and analyze historical LTS Events
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> event_source=lts \
  start_time="2026-05-30 06:00:00" end_time="2026-05-30 08:00:00"

# Analyze supplied Events without a cloud query
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  events='[{"type":"Warning","reason":"FailedScheduling","namespace":"default","count":3}]' \
  max_groups=10

リスクレベル

このスキルは読み取り専用です。クラウドリソース、Kubernetes リソース、LTS 設定、またはローカルのクラスターアクセス設定を変更することはありません。

レベル	意味	実行ガイダンス
R3	読み取り専用のイベントクエリ、またはローカルでのイベント分析	自動的に実行できます

ツール	操作タイプ	リスクレベル	説明
huawei_get_cce_events	クエリ	R3	kubectl を通じて現在のクラスターまたは名前空間のイベントをクエリします
huawei_query_k8s_events_from_lts	クエリ	R3	設定済みの LTS コレクションから過去のイベントレコードをクエリします
huawei_analyze_cce_events	クエリと分析	R3	必要に応じて現在または LTS のイベントをクエリし、タイプ、理由、名前空間、リソースごとに集計します

パラメーターリファレンス

共通パラメーター

パラメーター	必須／任意	説明	デフォルト
region	必須	Huawei Cloud のリージョン	HUAWEI_REGION
cluster_id	必須	CCE クラスターの正確な ID	N/A
ak	任意	対応するアクセス方法で使用する明示的な AK	プロファイル／環境変数にフォールバック
sk	任意	対応するアクセス方法で使用する明示的な SK	プロファイル／環境変数にフォールバック
project_id	kubectl cce では必須、それ以外では任意	対象クラスターの Huawei Cloud プロジェクト ID	外部 kubeconfig アクセスでは hcloud プロファイル／IAM／環境変数にフォールバック

現在のイベントクエリパラメーター

ツール	必須	任意
huawei_get_cce_events	region、cluster_id	namespace、event_type（デフォルトは Warning、または Normal、all）、limit、ak、sk、project_id（kubectl cce では必須）、security_token

過去のイベントクエリパラメーター

ツール	必須	任意
huawei_query_k8s_events_from_lts	region、cluster_id、start_time、end_time、project_id	event_type（デフォルトは Warning、または Normal、all）、keywords（event_type=all が必要）、ak、sk

イベント分析パラメーター

ツール	必須	任意
huawei_analyze_cce_events	events、または region ＋ cluster_id のいずれか	event_source（デフォルトは current、または lts）、start_time／end_time（lts では必須）、namespace、event_type、keywords、limit、max_groups（1～100、デフォルトは 10）、check_resource_status（region と cluster_id がある場合はデフォルトで true）、ak、sk、project_id、security_token

出力形式

公開レスポンスフィールド、Event レコードフィールド、リソースステータスの状態はすべて output-schema.md で定義されています。このリファレンスが出力コントラクトの唯一の信頼できる情報源です。

ワークフロー

1. region、正確な cluster_id、任意の namespace、インシデントの時間範囲を特定します。
2. 現在の Event を調査するには huawei_get_cce_events を使用します。
3. 1 時間を超える過去の Event の時間範囲、または正確な LTS 時間範囲やキーワードによる絞り込みが必要な場合は、huawei_query_k8s_events_from_lts を使用します。
4. 返された events を huawei_analyze_cce_events に渡し、理由、namespace、リソース、繰り返し発生するパターンを集計します。
5. エビデンスを、該当する Pod、Workload、Node、Storage、または Network の診断スキルに引き継ぎます。

パターン認識と時間範囲分析のガイダンスについては、workflow.md を参照してください。

検証

まず、現在の Event をクエリします。

python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> limit=10

デフォルトの Event-to-LTS 収集が有効な場合は、範囲を限定した過去のクエリを検証します。

python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 06:00:00" \
  end_time="2026-05-30 07:00:00"

現在の Event レスポンスに access_method が含まれていること、および LTS レスポンスでデフォルトの LTS グループとストリームが特定されていることを確認します。検証の一環として、ログ設定を作成または変更しないでください。

ベストプラクティス

1. 警告から始める - 詳細に調査する前に、type == "Warning" で絞り込みます。
2. 理由ごとにグループ化する - 理由の繰り返しから、個々のレコードを調べるよりも迅速にシステム上の問題を把握できます。
3. 正確なクラスター ID を使用する - クラスター名から ID を推測しないでください。
4. LTS の時間範囲を限定する - 問題の把握に必要な最小限のインシデント時間範囲を使用します。
5. 履歴には LTS を使用する - Kubernetes の現在の Event は保持期間が限られています。
6. 修復ではなく引き継ぎを行う - このスキルが提供するのはエビデンスのみです。

注意事項

• 警告が現在発生していないからといって、クラスターが健全であるとは限りません。利用可能な場合は、最近のインシデントや復旧済みのインシデントを確認するため、過去の LTS Event を調査してください。
• Event-to-LTS の経路は、デフォルトの Event 収集が有効な、正常に動作する log-agent アドオンに依存します。
• Event の要約では、閲覧者が必要としない場合、機密性の高い本番ワークロード、Pod、ノードの識別情報をマスキングしてください。
• このスキルを通じて Kubernetes、CCE ロギング、LTS、またはクラウドリソースを変更しないでください。

トラブルシューティング

症状	考えられる原因	対処方法
外部 kubeconfig へのアクセスに失敗する	外部エンドポイントがない、プロファイルが無効、または CCE 権限が不足している	cce:cluster:get と cce:cluster:createCert を確認してください。その後、ツールは kubectl cce を試行します
kubectl cce へのフォールバックに失敗する	プラグインがない、またはプラグインの認証情報を利用できない	kubectl-cce.md に従ってプラグインをインストール／設定してください
LTS クエリでデフォルトの Event ストリームが見つからない	デフォルトの Event 収集が有効になっていない、またはプロビジョニングが完了していない	log-agent アドオンからデフォルトの Event 収集を有効にしてから、再試行してください
LTS クエリでレコードが返されない	時間範囲、キーワード、保持期間、または Event 収集が一致していない	時間範囲を絞り込むか修正し、デフォルトの LTS グループとストリームを確認してください
現在の Event が多すぎる	クラスター全体に対する広範なクエリ	デフォルトでは Warning が対象です。データをソース側でさらに絞り込むには、namespace とより小さい limit を指定してください
権限が拒否される	IAM または Kubernetes RBAC 権限が不足している	報告された最小権限を付与してから、再試行してください

制限事項

• このスキルが提供するのは、ドキュメントに記載された読み取り専用 Event ツール 2 つのみです。
• 現在の Event クエリでサーバー側の選択に対応しているのは、namespace と Event タイプ（Warning、Normal、または all）のみです。
• 過去のクエリには、インシデント発生前にデフォルトの Event-to-LTS 収集が有効になっている必要があります。このスキルでは、収集されていない過去のデータを復元できません。
• このスキルでは、LTS ストリーム、Kubernetes リソース、CCE リソースを作成、変更、削除できません。
• このスキルでは、クラスター、namespace、イベントフィルター、診断／修復アクションをユーザーに代わって自動選択しません。

参考資料

ドキュメント	用途
ワークフロー	Event クエリの手順、グループ化、パターン、時間範囲の分析
リスクルール	読み取り専用の境界、編集、引き継ぎの制約
出力スキーマ	クエリ、分析、Event レコードのフィールド
kubectl-cce	kubectl-cce のインストール、認証情報、アクセスのフォールバック
受け入れ基準	現在、過去、およびクエリと分析を組み合わせたフローで期待される結果