G-gen の佐々木です。当記事では Kubernetes のためのオープンソースのログビューアである、Kubernetes History Inspector を使用してみます。

Kubernetes History Inspector とは

Kubernetes History Inspector（以下、KHI）は Google Cloud が OSS（オープンソースソフトウェア）として公開している Kubernetes クラスタ用のログ可視化ツールです。

Kubernetes はシステムコンポーネントも含め非常に多くのログを出力するため、クラスタ上で問題が発生した際には、膨大なログとリソースの関連性を読み解く労力が必要です。

KHI を使用することで、クラスタから出力される大量のログをインタラクティブな GUI でクエリ・可視化し、問題のトラブルシューティングを効率的に行うことができます。

KHI には以下の特徴があり、Google Cloud で Google Kubernetes Engine（GKE）を利用している環境では手軽に導入することができます。

クラスタに対するエージェント等の導入は不要（事前設定不要）
GUI を使用した簡素なクエリ実行・ログの可視化
ログがバックエンド（Cloud Logging）に保存されている限り、過去に遡ったログの分析が可能
KHI ファイルを使用したクエリ結果の保存・共有

また、ログ可視化の対象は GKE だけでなく、Cloud Composer、GKE on AWS、GKE on Azure などの環境にも対応しています。

KHI は Google Cloud の商用プロダクトではなく、GitHub リポジトリでソースコードが公開されています。KHI は、Docker イメージもしくはソースコードから実行することができます。

GitHub - Kubernetes History Inspector

KHI に必要な IAM 権限

クエリの実行

クエリの実行には、GKE クラスタのログが記録されている Cloud Logging に対する閲覧者権限が必要です。当記事ではログ閲覧者（roles/logging.viewer）ロールを付与した Google アカウントで操作しています。

Cloud Logging の閲覧権限がない場合、以下のようにクエリ実行時にエラーが出てしまいます。

当記事では Kubernetes Engine Cluster 閲覧者（roles/container.clusterViewer）ロールも使用しますが、こちらは必須ではありません。クラスタの閲覧権限があると、クエリ設定で対象クラスタを入力する際に、候補となるクラスタが表示されます。この権限がなくてもクラスタ名は手動で入力することができ、クエリの実行も成功します。

クラスタの閲覧権限がないと、クエリ対象のクラスタ候補が表示されない（クエリ実行は可能）

KHI ファイルのインポート

クエリした結果は KHI ファイル としてエクスポートすることで、クエリ結果の保存、共有を簡単に行うことができます。

KHI ファイルをインポートする際は Cloud Logging に対するクエリが実行されないため、Cloud Logging の読み取り権限を持っていなくてもビュー（クエリ結果）を確認することができます。つまり、KHI を実行することができる環境であれば、同じビューを表示できるということになります。

このことから、KHI ファイルはログを外部に共有する際に役立ちますが、エクスポートしたファイルの取り扱いには十分な注意が必要となります。

事前準備

当記事で利用する環境

当記事では、KHI の Docker イメージを使用して、GKE クラスタ上の Pod としてデプロイしていきます。

Kubernetes は以下のバージョンを使用しています。

$ kubectl version
Client Version: v1.29.2
Server Version: v1.30.8-gke.1128000

シェル変数の設定

事前準備で何度か使用する値を、シェル変数として設定しておきます。

# シェル変数の設定
PROJECT_ID={プロジェクトID}
SERVICE_ACCOUNT=khi-serviceaccount
NAMESPACE=default

Pod 用の ServiceAccount リソースの作成

KHI は Cloud Logging からログを読み込むため、Pod 上で実行する場合は、Pod に紐付けるサービスアカウントに対して IAM 権限を付与する必要があります。

まず、GKE クラスタ上に Pod に紐付けるための ServiceAccount リソースを作成します。

# ServiceAccount リソースを作成
$ kubectl create serviceaccount ${SERVICE_ACCOUNT}

Workload Identity Federation の設定

Workload Identity Federation を使用し、先ほど作成した ServiceAccount に対して IAM 権限を付与します。

GKE における Workload Identity Federation の詳細については、以下の記事をご一読ください。

blog.g-gen.co.jp

もし Kubernetes History Inspector の Pod に default 以外の Namespace を使用する場合は、NAMESPACE 変数の値も変更してください。

Workload Identity Federation の設定にはプロジェクト番号を使用する必要があるため、以下のコマンドでプロジェクト番号も取得して変数に設定しておきます。

# シェル変数にプロジェクト番号を設定する
$ PROJECT_NUM=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")

IAM ロールの付与

Workload Identity Federation を使用して、ServiceAccount に IAM ロールを付与していきます。

まず、ログ取得のためのログ閲覧者（roles/logging.viewer）ロールを付与します。

# ServiceAccout にログ閲覧者ロールを紐づけ
$ gcloud projects add-iam-policy-binding projects/${PROJECT_ID} \
    --role=roles/logging.viewer \
    --member=principal://iam.googleapis.com/projects/${PROJECT_NUM}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${NAMESPACE}/sa/${SERVICE_ACCOUNT}

また、ログ取得対象のクラスタの情報を取得するため、Kubernetes Engine Cluster 閲覧者（roles/container.clusterViewer）ロールも付与します。前述したように、このロールは付与しなくても問題ありません。

# ServiceAccout に Kubernetes Engine Cluster 閲覧者ロールを紐づけ
$ gcloud projects add-iam-policy-binding projects/${PROJECT_ID} \
    --role=roles/container.clusterViewer \
    --member=principal://iam.googleapis.com/projects/${PROJECT_NUM}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${NAMESPACE}/sa/${SERVICE_ACCOUNT}

Pod のデプロイ

以下のマニフェストファイルを使用して、Kubernetes History Inspector を実行する Pod を GKE クラスタ上にデプロイします。

# khi-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: khi-pod
spec:
  serviceAccountName: khi-serviceaccount
  containers:
  - name: khi-container
    image: asia.gcr.io/kubernetes-history-inspector/release:latest
    ports:
    - containerPort: 8080

KHI の Pod にアクセス

Kubernetes では、LoadBalancer や Ingress などのリソースを使用しなくても、ポートフォワードを使用して Service や Pod にアクセスすることができます。

以下のコマンドを実行し、127.0.0.1:8080 から Kubernetes History Inspector の Pod にポートフォワードできるようにします。

$ kubectl port-forward pods/khi-pod 8080:8080

ブラウザから 127.0.0.1:8080 にアクセスすると、KHI の GUI が表示されます。

KHI の操作

ログのクエリ

ユーザーガイドに従って操作を進めていきます。

[New inspection] からログのクエリを行います。

当記事では GKE のログをクエリするため、クラスタタイプとして「Google Kubernetes Engine」を選択します。

次の画面では、取得対象のログの種類を選択します。Kubernetes リソースの作成や GKE クラスタ自体の監査ログや、ワーカーノードのログ、コンテナ上のアプリケーションログなどのカテゴリから、必要となる種類のログをここで選択します。当記事ではデフォルトの設定値のまま進めていきます。

最後に、ログを取得する期間と、対象のプロジェクト、GKE クラスタ名、名前空間などの情報を設定します。

End time 項目で「いつまでのログを取得するか」を指定し、Duration 項目で「Endtime に設定した時間からどれくらい遡ってログを取得するか」を指定します。

たとえば、Endtime に 2025-01-29T20:30:00+09:00、Duration に 1h を設定すると、2025-01-29T19:30:00+09:00 ~ 2025-01-29T20:30:00+09:00 のログを取得することになります。

同じ画面で、対象の GKE クラスタや名前空間などの情報を入力します。プロジェクト ID を入力すると、候補となるクラスタの一覧が表示されます。

[Run] を押下すると、ここまで入力した情報を元にクエリが実行されます。クエリが完了するまで待ちます。

クエリが完了したら、[Open] からビューを開きます。

ビューの表示

ビューはタイムラインビュー、ログビュー、ヒストリービューの3つのコンポーネントから構成されています。

コンポーネント	説明
タイムラインビュー	ログ取得時に指定した期間をタイムラインとして帯状に表示し、クラスタ上のリソースごとのステータスやログの発生状況を可視化する。
ログビュー	クラスタ上で発生したログの内容を表示する。タイムラインビューでリソースを選択すると、選択したリソースでフィルタリングされたログビューが表示される。
ヒストリービュー	タイムラインビューで選択したリソースの変更履歴が差分表示される。