<img alt="Kubernetes History Inspector" src="https://github.com/GoogleCloudPlatform/khi/raw/v0.56.7/docs/images/logo-light.svg" width="50%">

Language: English | 日本語

Kubernetes History Inspector

Kubernetes History Inspector (KHI) は、Kubernetes クラスタのログ可視化ツールです。 大量のログをインタラクティブなタイムラインビューなどで可視化し、Kubernetes クラスタ内の複数のコンポーネントにまたがる複雑な問題のトラブルシューティングを強力にサポートします。

クラスタ内へのエージェント等のインストールの必要はなく、ログを読み込ませるだけで、トラブルシューティングに役立つ以下のログの可視化を提供します。

タイムラインビュー	クラスタダイアグラム
監査ログ等から特定期間の複数リソースに対する変更、ステータス等の遷移をわかりやすくタイムライン、差分として表示。	kube-apiserverの監査ログから復元した特定タイミングのリソースの関係性をわかりやすく可視化。

KHIの特徴

ログの可視化

KHIの主要な強みは、従来のテキストベースのログ分析を超えて、各Kubernetesリソースに関連する多数のアクティビティログをタイムラインベースのグラフとして視覚化できる点です。 単一のリソースでログを手動でフィルタリングしたり、個々のアクティビティログをテキストデータで時系列に読み進めたりする必要はありません。KHIを使用すると、タイムラインの視覚化から何が起こったのかを一目で把握できます。

また、ログの視覚化に加えて、KHIでは特定の瞬間のログデータを従来のテキスト形式で確認したり、特定のイベント発生時のYAMLマニフェストの差分を確認したりことも可能です。これにより、事象の原因を特定するプロセスが大幅に簡素化されます。

さらに、KHIはある特定の時点でのKubernetesクラスターのリソースの状態とその関係を示すクラスタダイアグラムを生成することもできます。これは、インシデント発生時の特定の時間におけるリソースのステータスやクラスターのトポロジーを理解する上で非常に役に立ちます。

エージェントレス

KHIのセットアップはとても簡単です。エージェントレスなので、対象クラスターに複雑な事前設定をすることなく、誰でも簡単に使い始めることができます。また、KHIはGUI操作でKubernetesログを視覚化できます。ログの取得のために複雑なクエリやコマンドを記述する必要はありません。

トラブルシューティングの知見

KHIは、Google Cloud サポートチームが開発し、その後オープンソース化されました。Google Cloudのサポートエンジニアが日々の業務でKubernetesログを分析する中で培った経験から生まれたツールです。KHIには、Kubernetesのログトラブルシューティングにおける彼らの深い専門知識が凝縮されています。

サポートされている製品

Kubernetes クラスタ

• Google Cloud

• Google Kubernetes Engine

• Cloud Composer
• GKE on AWS
• GKE on Azure
• GDCV for Baremetal

• GDCV for VMWare

• その他環境

• JSONlines 形式の kube-apiserver 監査ログ (チュートリアル (Using KHI with OSS Kubernetes Clusters - Example with Loki | 英語のみ))

ログバックエンド

• Google Cloud

• Cloud Logging（Google Cloud 上のすべてのクラスタ）

• その他環境

• ファイルによるログアップロード(チュートリアル (Using KHI with OSS Kubernetes Clusters - Example with Loki | 英語のみ))

実行方法

Docker イメージから実行

動作環境

• Google Chrome（最新版）
• docker コマンド

[!IMPORTANT] KHI は最新のGoogle Chromeでしかテストされていません。 他のブラウザでも動作する可能性はありますが、動作しない場合でもプロジェクトとしてサポートしていません。

[!IMPORTANT] Chrome 139以降、GPUを搭載していない環境では、CPUベースのWebGLエミュレーションが無効化されました。 リモートデスクトップ経由でGPU非搭載のサーバーからKHIにアクセスしている場合、タイムラインが正しく描画されない可能性があります。 この問題を解決するには、chrome://flags/#ignore-gpu-blocklist の設定を Enabled に変更してください。

注: ほとんどのコンシューマー向けラップトップ（専用グラフィックスカードを搭載していないものを含む）は、iGPUが搭載されているはずですのでこの影響は受けません。

KHI の実行

1. Cloud Shell を開きます。
2. docker run -p 127.0.0.1:8080:8080 gcr.io/kubernetes-history-inspector/release:latest を実行します。
3. ターミナル上のリンク http://localhost:8080 をクリックして、KHI の使用を開始してください！

[!WARNING] コンテナイメージのレポジトリが asia.gcr.io から gcr.io に変更されました。古いレポジトリも当面の間利用可能ですが、将来的には廃止される予定のため、新しいレポジトリへの切り替えを推奨します。

[!TIP] メタデータサーバが利用できない他の環境で KHI を実行する場合は、アプリケーションのデフォルト認証情報をホストのファイルシステムからコンテナにマウントして認証できます。

Linux, MacOS or WSL 環境

bash gcloud auth application-default login docker run \ -p 127.0.0.1:8080:8080 \ -v ~/.config/gcloud/application_default_credentials.json:/root/.config/gcloud/application_default_credentials.json:ro \ gcr.io/kubernetes-history-inspector/release:latest

Windows PowerShell 環境

bash gcloud auth application-default login docker run ` -p 127.0.0.1:8080:8080 ` -v $env:APPDATA\gcloud\application_default_credentials.json:/root/.config/gcloud/application_default_credentials.json:ro ` gcr.io/kubernetes-history-inspector/release:latest

詳細は Getting Started を参照してください。

ソースから実行

動かしてみる (ソースから実行)

ビルドに必要な依存関係

• Go 1.25.*
• Node.js 環境 22.13.*
• gcloud CLI
• jqコマンド

環境構築

1. このリポジトリをダウンロードまたはクローンします。
   例: git clone https://github.com/GoogleCloudPlatform/khi.git
2. プロジェクトルートに移動します。
   例: cd khi
3. プロジェクトルートから make setup を実行します。 (この Make ターゲットは、npm パッケージのインストール、自動生成コードの生成、git フックの設定を行います)

KHI のビルドと実行

1. gcloud で認証します。
   例: ユーザーアカウントの認証情報を使用する場合は、gcloud auth login を実行します。
2. make build を実行します。
3. 生成された実行ファイル ./khi を実行します。
4. http://localhost:8080 を開き、KHI の使用を開始してください！

[!IMPORTANT] KHI のポートをインターネット向けに公開しないでください。 KHI 自身は認証、認可の機能を提供しておらず、ローカルユーザからのみアクセスされることが想定されています。

権限設定

マネージド環境毎の設定

Google Cloud

権限

以下の権限が必須・推奨されます。

• 必須権限
• logging.logEntries.list
• 推奨権限
• New Inspectionダイアログでの入力時にオートコンプリートの入力候補を取得するために使用します。権限がなくても問題がありませんが、入力時にクラスタ名の候補が表示されません。
  • monitoring.timeSeries.list
  • container.clusters.list (Cloud Composer向け機能利用時のみ)

• 設定手順

• Compute Engine 仮想マシン上など、サービスアカウントがアタッチされた Google Cloud 環境で KHI を実行する場合、対応するリソースにアタッチされたサービスアカウントに上記権限を付与します。

• ローカル環境や Cloud Shell など、ユーザアカウント権限で KHI を実行する場合、対応するユーザ上記権限を付与します。

監査ログ出力設定

• 必須設定無し
• 推奨設定
• Kubernetes Engine API データ書き込み監査ログの有効化

[!TIP] Pod や Node リソースの.statusフィールドへのパッチリクエストが記録されており、 トラブルシューティングに詳細なコンテナの情報も必要な場合に推奨されます。 Kubernetes Engine API データ書き込み監査ログが未出力の場合も、KHI は Pod 削除時の監査ログから最終のコンテナの状態を表示できますが、Pod が削除されない間のコンテナの状態変化が記録されません。

• 設定手順
• Google Cloud コンソールで、監査ログページに移動します。
• 「データアクセス監査ログの構成」以下の、「サービス」列から「Kubernetes Engine API」を選択します。
• 「ログタイプ」タブで、「データ書き込み」を選択します。
• 「保存」をクリックします。

OSS Kubernetes

OSS Kubernetesクラスタのログの可視化（Loki）を参照してください。

ユーザーガイド

ユーザーガイド をご確認ください。

KHIプロジェクトへの貢献

プロジェクトへの貢献をご希望の場合は、コントリビューションガイド をお読みの上、KHI開発環境のセットアップを実施してください。

免責事項

KHI は Google Cloud の公式製品ではございません。不具合のご報告や機能に関するご要望がございましたら、お手数ですが当リポジトリのGithub issuesにご登録ください。可能な範囲で対応させていただきます。