GKE でログが表示されない場合のトラブルシューティング

Autopilot Standard

Google Kubernetes Engine（GKE）のロギング パイプラインで問題が発生すると、クラスタログが Cloud Logging に表示されなくなり、モニタリングとデバッグの作業が妨げられる可能性があります。

このドキュメントでは、構成と権限の確認、リソースとパフォーマンスの問題の解決、フィルタとアプリケーションの動作の調査、ログに影響するプラットフォームまたはサービスの問題の解決を行う方法について説明します。

この情報は、クラスタのオブザーバビリティを維持するプラットフォーム管理者とオペレーター、および Cloud Logging を使用して GKE オペレーションのトラブルシューティングを行うユーザーにとって重要です。 Google Cloud コンテンツで使用されている一般的なロールとタスク例については、GKE Enterprise ユーザーの一般的なロールとタスクをご覧ください。

ログを使用してワークロードやクラスタのトラブルシューティングを行う方法の詳細については、Cloud Logging で履歴分析を行うをご覧ください。

症状から解決策を探す

ログが表示されない問題に関連する特定の症状が見られた場合は、次の表を使用してトラブルシューティングのアドバイスを確認してください。

カテゴリ	症状または観察	考えられる原因	トラブルシューティング手順
構成	プロジェクト内のすべてのクラスタのログが表示されない。	プロジェクトで Cloud Logging API が無効になっている。	Cloud Logging API のステータスを確認する
	特定のクラスタのログが表示されないか、特定のログタイプのみが表示されない。	必要なログタイプでクラスタレベルのロギングが無効になっている。	クラスタのロギング構成を確認する
	特定のノードプールのノードのログが表示されない。	ノードプールのノードに必要なアクセス スコープがない。	ノードプールのアクセス スコープを確認する
	Logging エージェントのログに権限エラー（401 または 403）が表示される。	ノードのサービス アカウントに必要な権限がない。	ノードのサービス アカウントの権限を確認する
リソースとパフォーマンス	ログが断続的に取得されないか、RESOURCE_EXHAUSTED エラーが表示される。	プロジェクトが Cloud Logging API の書き込み割り当てを超過している。	Cloud Logging API の割り当て使用量を調査する
	（多くの場合、トラフィックが多いときや負荷が高いときに）特定のノードのログが取得されない。	ノードが Logging エージェントのスループット上限を超過しているか、ログを処理するリソース（CPU またはメモリ）が不足している。	ノードのスループットとリソース使用量を調査する
フィルタリングとアプリケーションの動作	特定のパターンに一致する特定のログが常に表示されない。	Cloud Logging のログ除外フィルタによって意図せずログがドロップされている。	ログ除外フィルタを調査する
	コンテナからのログが大幅に遅延するか、コンテナの終了後にのみ表示される。	（多くの場合、stdout のパイプ処理が原因で）アプリケーションの出力が完全にバッファリングされている。	コンテナログのバッファリングと遅延を調査する
	想定されるログが検索結果に表示されない。	ログ エクスプローラのクエリフィルタが過度に制限されている。	ログ エクスプローラのクエリを調査する
	特定のアプリケーション Pod のログは表示されないが、他のクラスタログは表示される。	コンテナ内のアプリケーションが stdout または stderr に書き込んでいない。	アプリケーション固有のロギング動作を調査する
プラットフォームとサービス	特定の日付より古いログが表示されない。	ログの保持期間が経過して、Cloud Logging によって削除された。	ログの保持期間を調査する
	プロジェクトまたはクラスタ全体でログの損失や遅延が広範囲に発生している。	Cloud Logging サービスの問題または取り込みの遅延。	Cloud Logging サービスの問題と遅延を調査する
	ロギングの問題がクラスタ バージョンの制限と一致する。	GKE バージョンがサポートされていない。	クラスタ バージョンを調査する

自動診断ツールを使用する

以降のセクションでは、クラスタの一般的な構成ミスを自動的に検査し、複雑な問題を調査するうえで役立つツールについて説明します。

gcpdiag を使用して GKE のロギングの問題をデバッグする

GKE クラスタのログが取得されない場合や、不完全なログが取得される場合は、gcpdiag ツールを使用してトラブルシューティングを行います。

gcpdiag はオープンソース ツールです。正式にサポートされている Google Cloud プロダクトではありません。gcpdiag ツールを使用すると、 Google Cloudプロジェクトの問題を特定して修正できます。詳細については、GitHub の gcpdiag プロジェクトをご覧ください。

GKE クラスタのログが取得されない場合や不完全な場合は、次のコア構成の設定に焦点を当てて、考えられる原因を調査します。

• プロジェクト レベルのロギング: GKE クラスタが格納されている Google Cloudプロジェクトで Cloud Logging API が有効になっていることを確認します。
• クラスタレベルのロギング: GKE クラスタの構成内でロギングが明示的に有効になっていることを確認します。
• ノードプールの権限: クラスタのノードプール内のノードで Cloud Logging Write スコープが有効になっていることを確認します。有効になっていれば、ログデータが送信されます。
• サービス アカウントの権限: ノードプールで使用されるサービス アカウントに、Cloud Logging の操作に必要な IAM 権限があることを確認します。通常は roles/logging.logWriter ロールが必要です。
• Cloud Logging API の書き込み割り当て: 指定された期間内に Cloud Logging API の書き込み割り当てが超過していないことを確認します。

Google Cloud コンソール

1. 次のコマンドを入力してコピーします。

gcpdiag runbook gke/logs \
    --parameter project_id=PROJECT_ID \
    --parameter name=CLUSTER_NAME \
    --parameter location=LOCATION

2. Google Cloud コンソールを開き、Cloud Shell を有効にします。
Cloud コンソールを開く
3. コピーしたコマンドを貼り付けます。
4. gcpdiag コマンドを実行します。gcpdiag Docker イメージがダウンロードされ、診断チェックが実行されます。必要に応じて、出力の指示に沿って、失敗したチェックを修正します。

Docker

Docker コンテナで gcpdiag を起動するラッパーを使用して gcpdiag を実行できます。Docker または Podman がインストールされている必要があります。

1. ローカル ワークステーションで次のコマンドをコピーして実行します。

   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag

2. gcpdiag コマンドを実行します。

   ./gcpdiag runbook gke/logs \
       --parameter project_id=PROJECT_ID \
       --parameter name=CLUSTER_NAME \
       --parameter location=LOCATION

このランブックで使用可能なパラメータを表示します。

次のように置き換えます。

• PROJECT_ID: リソースを含むプロジェクトの ID。
• CLUSTER_NAME: GKE クラスタの名前
• LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。

有用なフラグ:

• --universe-domain: 該当する場合、リソースをホストする信頼できるパートナーのソブリン クラウド ドメイン
• --parameter または -p: ランブック パラメータ

gcpdiag ツールのフラグの一覧と説明については、gcpdiag の使用手順をご覧ください。

Gemini Cloud Assist の調査を使用する

Gemini Cloud Assist の調査を使用して、ログに関する追加の分析情報を取得し、問題を解決することを検討してください。ログ エクスプローラを使用して調査を開始するさまざまな方法については、Gemini ドキュメントの Gemini Cloud Assist の調査を使用した問題のトラブルシューティングをご覧ください。

ロギング構成と権限を確認する

GKE ログが表示されない一般的な原因は、設定が正しくないことです。次のセクションを参考に、Cloud Logging の構成を確認します。

Cloud Logging API のステータスを確認する

プロジェクト内の任意のクラスタからログを収集するには、Cloud Logging API が有効になっている必要があります。

症状:

プロジェクト内のすべての GKE リソースのログが Cloud Logging に表示されない。

原因:

Google Cloud プロジェクトで Cloud Logging API が無効になっているため、ノードの Logging エージェントがログを送信できません。

解決策:

Cloud Logging API が有効になっていることを確認し、必要に応じて有効にするには、次のいずれかのオプションを選択します。

コンソール

1. Google Cloud コンソールで、[有効な API とサービス] ページに移動します。

   [有効な API とサービス] に移動

2. [ フィルタ] フィールドに「Cloud Logging API」と入力して、Enter キーを押します。

3. API が有効になっている場合は、一覧に表示されます。API が一覧に表示されない場合は、次の手順で有効にします。

   1. [ API とサービスを有効にする] をクリックします。
   2. [検索] フィールドに「Cloud Logging API」と入力し、Enter キーを押します。
   3. [Cloud Logging API] の結果をクリックします。
   4. [有効にする] をクリックします。

gcloud

1. API が有効になっているかどうかを確認します。

   gcloud services list --enabled --filter="NAME=logging.googleapis.com"
   

   出力は次のようになります。

   NAME: logging.googleapis.com
   TITLE: Cloud Logging API
   

2. API が有効なサービスの一覧に表示されない場合は、次の手順で有効にします。

   gcloud services enable logging.googleapis.com \
       --project=PROJECT_ID
   

   PROJECT_ID は、実際の Google Cloudプロジェクト ID に置き換えます。

クラスタのロギング構成を確認する

GKE では、クラスタから収集するログタイプ（SYSTEM や WORKLOAD など）を構成できます。

症状:

特定の GKE クラスタのログが Cloud Logging に表示されない、または特定のログタイプ（SYSTEM など）のみが表示されない。

原因:

必要なログタイプでクラスタレベルのロギングが無効になっています。Autopilot クラスタを使用している場合、これはロギングの問題の原因ではありません。この設定は Standard クラスタでは構成できますが、Autopilot クラスタではデフォルトで常に有効になっており、無効にすることはできません。

解決策:

クラスタのロギング構成を確認して更新するには、次のいずれかのオプションを選択します。

コンソール

1. Google Cloud コンソールで [Kubernetes クラスタ] ページに移動します。

   [Kubernetes クラスタ] に移動

2. 調査するクラスタの名前をクリックします。

3. [詳細] タブをクリックし、[機能] セクションに移動します。

4. [ロギング] 行で、有効になっているログタイプ（システム、ワークロードなど）を確認します。

5. 収集するログタイプが無効になっているか、正しくない場合は、[ Logging の編集] をクリックします。

6. [コンポーネント] リストで、収集するログタイプのチェックボックスをオンにして、[OK] をクリックします。使用可能なログタイプの詳細については、GKE ログについてをご覧ください。

7. [変更を保存] をクリックします。

gcloud

1. ロギング構成を確認するには、クラスタの説明を取得します。

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(name,loggingConfig.componentConfig.enableComponents)"
   

   次のように置き換えます。

   • CLUSTER_NAME: クラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

   ロギングが有効になっている場合、出力は次のようになります。

   example-cluster    SYSTEM_COMPONENTS;WORKLOADS
   

   出力が NONE の場合、ロギングは無効になっています。

2. 必要なログタイプが無効になっているか、正しくない場合は、ロギング構成を更新します。

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=LOGGING_TYPE
   

   LOGGING_TYPE は、SYSTEM、WORKLOAD、またはその両方に置き換えます。ログを収集するには、SYSTEM を有効にする必要があります。WORKLOAD ログのみを収集することはできません。使用可能なログタイプの詳細については、GKE ログについてをご覧ください。

ノードプールのアクセス スコープを確認する

GKE クラスタ内のノードは、OAuth アクセス スコープを使用して、Cloud Logging などの Google Cloud API を操作する権限を取得します。

症状:

特定のノードプールのノードのログが表示されない。

原因:

ノードプール内のノードに必要な OAuth アクセス スコープがありません。ノードが Cloud Logging にログを書き込むには、次のいずれかのスコープが必要です。

• https://www.googleapis.com/auth/logging.write: ログを書き込む権限を付与します。これは、最低限必要なスコープです。
• https://www.googleapis.com/auth/logging.admin: Cloud Logging API への完全アクセス権を付与します。logging.write の権限が含まれます。
• https://www.googleapis.com/auth/cloud-platform: 有効になっているすべての Google Cloud API への完全アクセス権を付与します。logging.write の権限が含まれます。

解決策:

権限を確認し、必要なロールがない場合に付与するには、次のいずれかのオプションを選択します。

コンソール

1. ノードプールのアクセス スコープを確認します。

   1. Google Cloud コンソールで [Kubernetes クラスタ] ページに移動します。

      [Kubernetes クラスタ] に移動

   2. クラスタの詳細ページを開くには、調査するクラスタの名前をクリックします。

   3. [ノード] タブをクリックします。

   4. [ノードプール] セクションで、調査するノードプールの名前をクリックします。

   5. [セキュリティ] セクションに移動します。

   6. [アクセス スコープ] フィールドに表示されているスコープを確認します。次の必要なスコープのいずれかが存在することを確認します。

      • Stackdriver Logging API - 書き込み専用
      • Stackdriver Logging API - フル
      • Cloud Platform - 有効

      必要なスコープがない場合は、ノードプールを再作成します。既存のノードプールのアクセス スコープは変更できません。

2. 必要に応じて、必要なスコープを持つ新しいノードプールを作成します。

   1. 変更するクラスタの詳細ページに戻ります。
   2. [ノード] タブをクリックします。
   3. [ ユーザー管理のノードプールを作成] をクリックします。
   4. [ノードプールの詳細] セクションに入力します。
   5. 左側のナビゲーションで [セキュリティ] をクリックします。
   6. [アクセス スコープ] セクションで、追加するロールを選択します。
      • 特定のスコープを追加するには、[各 API にアクセス権を設定] を選択します。
      • 完全アクセスを許可するには、[すべての Cloud API に完全アクセス権を許可] を選択します。
   7. 必要に応じて、他のセクションを構成します。
   8. [作成] をクリックします。

3. ワークロードを新しいノードプールに移行します。ワークロードを新しいノードプールに移行すると、アプリケーションは Cloud Logging にログを送信するために必要なスコープを持つノードで実行されます。

4. 古いノードプールを削除します。

   1. クラスタの詳細ページに戻り、[ノード] タブを選択します。
   2. [ノードプール] セクションで、古いノードプールを見つけます。
   3. ノードプールの横にある [ 削除] をクリックします。
   4. プロンプトが表示されたら、ノードプールの名前を入力して削除を確定し、[削除] をクリックします。

gcloud

1. ノードプールのアクセス スコープを確認します。

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePools[].name,nodePools[].config.oauthScopes)"
   

   次のように置き換えます。

   • CLUSTER_NAME: クラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

   各ノードプールの出力を確認します。必要なスコープ（https://www.googleapis.com/auth/logging.write、https://www.googleapis.com/auth/cloud-platform、https://www.googleapis.com/auth/logging.admin）のいずれか 1 つ以上が表示されていることを確認します。必要なスコープがない場合は、ノードプールを再作成します。既存のノードプールのアクセス スコープは変更できません。

2. 必要に応じて、必要なスコープを持つ新しいノードプールを作成します。

   gcloud container node-pools create NEW_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --scopes=https://www.googleapis.com/auth/logging.write,OTHER_SCOPES
   

   次のように置き換えます。

   • NEW_NODE_POOL_NAME: 新しいノードプールの名前。
   • OTHER_SCOPES: ノードに必要な他のスコープのカンマ区切りのリスト。他のスコープが必要ない場合は、このプレースホルダと前のカンマを省略します。

3. ワークロードを新しいノードプールに移行します。ワークロードを新しいノードプールに移行すると、アプリケーションは Cloud Logging にログを送信するために必要なスコープを持つノードで実行されます。

4. 古いノードプールを削除します。

   gcloud container node-pools delete OLD_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID
   

ノードのサービス アカウントの権限を確認する

ノードはサービス アカウントを使用して Google Cloud サービスの認証を行います。このアカウントには、ログを書き込むための特定の IAM 権限が必要です。

症状:

• ノードのログが表示されない。
• Logging エージェントのログ（Fluent Bit など）を調べると、権限関連のエラー（Cloud Logging に書き込もうとした際の 401 または 403 コードなど）が見つかる。
• Google Cloud コンソールにクラスタの Grant Critical Permissions to Node Service Account 通知が表示される。

原因:

ノードプールのノードで使用されるサービス アカウントに、Cloud Logging にログを書き込むために必要な IAM 権限がありません。ノードには、logging.logEntries.create 権限を含む logging.logWriter ロールを持つサービス アカウントが必要です。

また、GKE バージョン 1.33 以降の場合、GKE デフォルト ノード サービス エージェント（[e-mail]）には、Kubernetes デフォルト ノード サービス エージェント（roles/container.defaultNodeServiceAgent）ロールが最低限必要です。このロールにより、GKE はロギング コンポーネントなどのノードリソースとオペレーションを管理できます。

解決策:

権限を確認し、必要なロールがない場合に付与するには、次の操作を行います。

• ノードのサービス アカウントの権限を確認する。
• GKE サービス エージェントに必要なロールがあることを確認する。

ノードのサービス アカウントの権限を確認する

ノードのサービス アカウントは、ノードが認証とログの送信に使用するアカウントです。このサービス アカウントを特定し、必要な roles/logging.logWriter 権限があることを確認するには、次の操作を行います。

1. ノードプールで使用されるサービス アカウントを特定するには、次のいずれかのオプションを選択します。

   コンソール

   1. Google Cloud コンソールで [Kubernetes クラスタ] ページに移動します。

      [Kubernetes クラスタ] に移動

   2. クラスタのリストで、調査するクラスタの名前をクリックします。

   3. クラスタの運用モードに応じて、次のいずれかを行います。

      • Standard クラスタの場合は、次の操作を行います。

        1. [ノード] タブをクリックします。
        2. [ノードプール] テーブルで、ノードプールの名前をクリックします。[ノードプールの詳細] ページが開きます。
        3. [セキュリティ] セクションで、[サービス アカウント] フィールドを見つけます。

      • Autopilot クラスタの場合は、次の操作を行います。

        1. [詳細] タブに移動します。
        2. [セキュリティ] セクションで、[サービス アカウント] フィールドを見つけます。

      [サービス アカウント] フィールドの値が default の場合、ノードは Compute Engine のデフォルトのサービス アカウントを使用します。このフィールドの値が default 以外の場合、ノードはカスタム サービス アカウントを使用します。カスタム サービス アカウントに必要なロールを付与するには、最小権限の IAM サービス アカウントを使用するをご覧ください。

   gcloud

   使用するクラスタのタイプに応じて、次のコマンドを実行します。

   Standard クラスタ

   gcloud container node-pools describe NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(config.serviceAccount)"
   

   次のように置き換えます。

   • NODE_POOL_NAME: ノードプールの名前。
   • CLUSTER_NAME: Standard クラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
   • PROJECT_ID: 実際の Google Cloudプロジェクト ID。

   出力が default の場合、ノードプールは Compute Engine のデフォルトのサービス アカウントを使用します。値が default 以外の場合、ノードはカスタム サービス アカウントを使用します。カスタム サービス アカウントに必要なロールを付与するには、最小権限の IAM サービス アカウントを使用するをご覧ください。

   Autopilot クラスタ

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePoolDefaults.nodeConfigDefaults.serviceAccount)"
   

   次のように置き換えます。

   • CLUSTER_NAME: Autopilot クラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

   出力が default の場合、ノードプールは Compute Engine のデフォルトのサービス アカウントを使用します。値が default 以外の場合、ノードはカスタム サービス アカウントを使用します。カスタム サービス アカウントに必要なロールを付与するには、最小権限の IAM サービス アカウントを使用するをご覧ください。

   不足している権限を特定するスクリプトの詳細については、権限のないノード サービス アカウントをすべて特定するをご覧ください。

2. GKE は、不足している権限を自動的にスキャンし、推奨事項を提供します。推奨事項を使用して不足している権限を確認するには、次のいずれかのオプションを選択します。

   コンソール

   1. [Kubernetes クラスタ] ページで、[通知] 列を見つけます。
   2. [通知] 列で、[重要な権限を付与します] の推奨事項を確認します。この推奨事項は、NODE_SA_MISSING_PERMISSIONS チェックが失敗したことを意味します。
   3. 推奨事項が表示されたら、クリックします。詳細パネルが開き、不足している権限の説明と、問題を解決する手順が表示されます。

   gcloud

   1. 不足しているサービス アカウントの権限に関する推奨事項を一覧表示します。

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. コマンド出力を分析します。

      • コマンドが空のリストを返した場合は、Recommender がアクティブな NODE_SA_MISSING_PERMISSIONS 推奨事項を見つけられていません。確認したサービス アカウントには、必要な権限があるようです。

      • コマンドが 1 つ以上の YAML ブロックを返した場合は、Recommender が権限の問題を特定しています。出力で次のキーフィールドを確認します。

        • description: ノードのサービス アカウントに roles/logging.logWriter ロールがない、GKE サービス エージェントに roles/container.defaultNodeServiceAgent ロールがないなど、問題の概要を示します。
        • resource: 影響を受けるクラスタを示します。
        • content.operations: 推奨される解決策が含まれます。このセクションでは、不足している特定のロールを付与するために必要な正確な gcloud projects add-iam-policy-binding コマンドを示します。

   Recommender が最新の変更を反映するまでに最大 24 時間かかることがあります。

3. 権限をすぐに確認してロールを付与するには、次のいずれかのオプションを選択します。

   コンソール

   1. Google Cloud コンソールで、[IAM] ページに移動します。

      [IAM] に移動

   2. ノードプールで使用されているサービス アカウントを確認します。

   3. [ロール] 列で、サービス アカウントにログ書き込み（roles/logging.logWriter）ロールがあるかどうかを確認します。

   4. 権限がない場合は、追加します。

      1. [ プリンシパルを編集] をクリックします。
      2. [ 別のロールを追加] をクリックします。
      3. 検索フィールドに「Logs Writer」と入力します。
      4. [ログ書き込み] チェックボックスをオンにして、[適用] をクリックします。
      5. [保存] をクリックします。

   gcloud

   1. ノードのサービス アカウントの現在のロールを確認します。

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT_EMAIL"
      

   2. logging.logWriter ロールがない場合は、付与します。

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/logging.logWriter"
      

GKE サービス エージェントの権限を確認する

ログがまだ表示されず、バージョン 1.33 以降を使用している場合は、GKE がノード コンポーネントの管理に使用する Google マネージド エージェントに必要な権限があることを確認します。

1. サービス エージェントのメールアドレスを確認するには、プロジェクト番号を取得します。

   gcloud projects describe PROJECT_ID --format="value(projectNumber)"
   

   PROJECT_ID は、実際のプロジェクト ID に置き換えます。出力をメモします。

   GKE サービス エージェントのメールアドレスは、[e-mail] です。

2. 推奨事項を使用して不足している権限を確認するには、次のいずれかのオプションを選択します。

   コンソール

   1. [Kubernetes クラスタ] ページで、[通知] 列を見つけます。
   2. [重要な権限を付与します] の推奨事項の列を確認します。
   3. 推奨事項が表示されたら、クリックします。詳細パネルが開き、不足している権限の説明と、問題を解決する手順が表示されます。

   gcloud

   1. 不足しているサービス アカウントの権限に関する推奨事項を一覧表示します。

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. コマンド出力を分析します。出力で、GKE サービス エージェント（gcp-sa-gkenode）に roles/container.defaultNodeServiceAgent ロールがないことを示す説明を確認します。

3. 権限をすぐに確認してロールを付与するには、次のいずれかのオプションを選択します。

   コンソール

   1. Google Cloud コンソールで、[IAM] ページに移動します。

      [IAM] に移動

   2. [ フィルタ] フィールドに GKE サービス エージェントのメールアドレスを入力し、Enter キーを押します。

   3. フィルタされたリストで、サービス エージェントに少なくとも Kubernetes デフォルト ノード サービス エージェント（roles/container.defaultNodeServiceAgent）ロールが付与されているかどうかを確認します。

   4. ロールがない場合は、付与します。

      1. サービス エージェントの横にある [ プリンシパルを編集] をクリックします。
      2. [ ロールを追加] をクリックします。
      3. 検索フィールドに「Kubernetes Default Node Service Agent」と入力し、ロールを選択します。
      4. [保存] をクリックします。

   gcloud

   1. roles/container.defaultNodeServiceAgent ロールがサービス エージェントにバインドされているかどうかを確認します。

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:[e-mail]"
      

      出力で roles/container.defaultNodeServiceAgent を探します。

   2. ロールがない場合は、Kubernetes デフォルト ノード サービス エージェント ロールを付与します。

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:[e-mail]" \
          --role="roles/container.defaultNodeServiceAgent"
      

リソースとパフォーマンスに関する問題のトラブルシューティング

ログが断続的に取得されない場合や、トラフィックの多いノードからドロップされている場合、原因は構成ミスではなく、パフォーマンスの問題である可能性があります。以降のセクションを参考に、プロジェクトが API 割り当てを超過していないかどうか、またはログの量が多くて特定のノードのエージェントが過負荷になっていないかどうかを調査します。

Cloud Logging API の割り当て使用量を調査する

サービスを保護するため、Cloud Logging はすべてのプロジェクトに書き込み割り当てを適用し、Cloud Logging が 1 分あたりに取り込むことができるログの合計量を制限します。

症状:

• ログが断続的または完全に取得されない。
• ノードまたは Logging エージェントのログに、logging.googleapis.com に関連する RESOURCE_EXHAUSTED エラーが表示される。

原因:

プロジェクトが Cloud Logging API の書き込みリクエストの割り当てを超過しています。この問題により、Logging エージェントがログを送信できません。

解決策:

割り当て使用量を確認して引き上げをリクエストする手順は次のとおりです。

1. Google Cloud コンソールで、[割り当て] ページに移動します。

   [割り当て] に移動

2. [ フィルタ] フィールドに「Cloud Logging API」と入力して、Enter キーを押します。

3. フィルタされたリストで、クラスタが存在するリージョンの [1 リージョン、1 分あたりのログ書き込みバイト数] の割り当てを見つけます。

4. [現在の使用率] 列の値を確認します。使用量が上限に達しているか、上限に近い場合は、割り当てを超過している可能性があります。

5. 引き上げをリクエストするには、[割り当てを編集] をクリックし、プロンプトに沿って操作します。詳細については、割り当ての表示と管理をご覧ください。

使用量を減らすには、ログを除外するか、アプリケーションのログの詳細度を下げることを検討してください。アラート ポリシーを設定して、上限に達する前に通知を受け取ることもできます。

ノードのスループットとリソース使用量を調査する

各ノードの GKE Logging エージェントには独自のスループット上限があり、この上限を超過することがあります。

症状:

特定のノードのログが断続的に取得されないか遅延する。特に、クラスタ アクティビティが多い期間やノードのリソース使用量が多い期間に発生する。

原因:

GKE Logging エージェントには、デフォルトのスループット上限（ノードあたり約 100 KBps）があります。ノード上のアプリケーションがこの上限を超える速度でログを生成すると、プロジェクト全体の API 割り当てが上限を超過していなくても、エージェントがログをドロップすることがあります。ノードのロギング スループットは、Metrics Explorer の kubernetes.io/node/logs/input_bytes 指標を使用してモニタリングできます。

ノードの CPU またはメモリの負荷が高く、エージェントがログを処理するために十分なリソースがない場合も、ログが取得されない可能性があります。

解決策:

スループットを低減するには、次のいずれかのオプションを選択します。

Standard クラスタ

次の解決策を試してください。

• 高スループットのロギングを有効にする: この機能により、ノードあたりの容量が増加します。詳細については、Cloud Logging エージェントのスループットを調整するをご覧ください。

• ログの量を減らす: アプリケーションのロギング パターンを分析します。不要なロギングや過度に詳細なロギングを減らします。

• カスタム Logging エージェントをデプロイする: 独自のカスタマイズされた Fluent Bit DaemonSet をデプロイして管理できますが、その構成とメンテナンスはお客様の責任となります。

• ノードのリソース使用量を確認する: ログの量が上限以下であっても、ノードの CPU またはメモリの負荷が高くないことを確認します。ノードリソースが不足していると、Logging エージェントがログを処理して送信する能力が妨げられる可能性があります。Metrics Explorer で kubernetes.io/node/cpu/core_usage_time や kubernetes.io/node/memory/used_bytes などの指標を確認します。

Autopilot クラスタ

次の解決策を試してください。

• ログの量を減らす: アプリケーションのロギング パターンを分析します。不要なロギングや過度に詳細なロギングを減らします。可能な限りログが構造化されていることを確認します。このようなログは、効率的な処理に役立ちます。重要でないログを除外します。

• アプリケーションのパフォーマンスを最適化する: Autopilot クラスタのノードリソースはマネージド型であるため、アプリケーションが CPU やメモリを過剰に消費していないことを確認します。過剰な消費は、Logging エージェントなどのノード コンポーネントのパフォーマンスに間接的に影響する可能性があります。ノードを直接管理することはありませんが、アプリケーションの効率はノード全体の健全性に影響します。

フィルタリングとアプリケーションに関する問題のトラブルシューティング

アプリケーションがログを正常に生成しても、Cloud Logging にログが表示されない場合、この問題は、フィルタリングまたはアプリケーションのロギング動作が原因となっていることがよくあります。以降のセクションでは、ログ除外フィルタ、コンテナレベルのバッファリング、制限付き検索クエリ、stdout または stderr に書き込まないアプリケーションなどの問題について説明します。

ログ除外フィルタを調査する

ログ エクスプローラには、クエリ内のすべてのフィルタと選択した期間に一致するログのみが表示されます。

症状:

特定の条件に一致する特定のログが Cloud Logging に表示されないが、同じソースの他のログは表示される。

原因:

ログ除外フィルタは、Cloud Logging シンク（通常は _Default シンク）で定義されます。ログがノードから正常に送信された場合でも、これらのルールにより、特定の条件に一致するログがサイレントにドロップされます。

解決策:

除外フィルタを確認して変更するには、次のいずれかのオプションを選択します。

コンソール

1. Google Cloud コンソールで、[ログルーター] ページに移動します。

   [ログルーター] に移動

2. 問題のあるフィルタを特定します。

   1. 各シンク（除外フィルタを設定できない _Required シンクを除く）で、[ その他の操作] をクリックし、[シンクの詳細を表示する] を選択します。
   2. [除外フィルタ] セクションでクエリを確認します。フィルタのロジックと、表示されないログの属性（リソースタイプ、ラベル、キーワードなど）を比較します。
   3. 除外フィルタクエリをコピーします。

   4. [ログ エクスプローラ] ページに移動します。

      [ログ エクスプローラ] に移動

   5. 除外フィルタクエリをクエリペインに貼り付けて、[クエリを実行] をクリックします。

   6. 結果を確認します。表示されるログは、フィルタによって除外されるログです。表示されないログがこれらの結果に表示された場合は、このフィルタが原因である可能性が高いと考えられます。

3. フィルタを無効にするか編集します。

   1. [ログルーター] ページに戻ります。
   2. 問題のあるフィルタを含むシンクの [ その他の操作] をクリックし、[シンクを編集] を選択します。
   3. [シンクに含めないログの選択] セクションで、除外フィルタを見つけます。
   4. [無効にする] をクリックしてフィルタを無効にするか、クエリを変更してより具体的にします。
   5. [シンクを更新] をクリックします。新しいログに変更が適用されます。

gcloud

1. プロジェクト内のすべてのシンクを一覧表示します。

   gcloud logging sinks list --project=PROJECT_ID
   

2. 各シンクの除外フィルタを表示します。

   gcloud logging sinks describe SINK_NAME --project=PROJECT_ID
   

   出力で、exclusions セクションを確認します。フィルタのロジックと、表示されないログの属性（リソースタイプ、ラベル、キーワードなど）を比較します。

3. 除外を変更するには、シンクの構成を更新します。

   1. シンクの構成をローカル ファイル（sink-config.yaml など）にエクスポートします。

      gcloud logging sinks describe SINK_NAME \
          --format=yaml > sink-config.yaml
      

   2. テキスト エディタで sink-config.yaml ファイルを開きます。

   3. exclusions: セクションを見つけて、問題のあるフィルタを削除または変更します。

   4. 変更されたシンクを更新します。

      gcloud logging sinks update SINK_NAME sink-config.yaml \
          --project=PROJECT_ID
      

      このコマンドの詳細については、gcloud logging sinks update ドキュメントをご覧ください。

コンテナログのバッファリングと遅延を調査する

アプリケーションやオペレーティング システムでは多くの場合、パフォーマンスを向上させるために、バッファリングを使用してデータを行単位ではなくチャンクで書き込みます。

症状:

• 特定のコンテナのログがコンテナの終了後にのみ Cloud Logging に表示されるか、ログの表示に大幅な遅延が発生する。
• ログが不完全な場合がある。

原因:

この問題は、ログのバッファリングが原因となっていることがよくあります。標準出力（stdout）は通常、ターミナルに接続されている場合は行バッファリングされますが、出力がパイプ処理されるとこの動作は変わります。コンテナパイプ内のアプリケーションのログまたは起動スクリプトが stdout を他のコマンド（my-app | grep ... など）にパイプ処理すると、出力が完全にバッファリングされることがあります。その結果、バッファがいっぱいになるか、パイプが閉じるまでログは保持されます。この動作により、コンテナが予期せず終了した場合に遅延やデータ損失が発生する可能性があります。アプリケーション内部のバッファリングも遅延の原因となることがあります。

解決策:

この問題を解決するには、次のことを試してください。

• stdout のパイプ処理を避ける: 可能であれば、コンテナのエントリ ポイントまたはアプリケーション コマンドを変更して、コンテナ内の grep や sed などの他のコマンドでパイプ処理を行わずに、ログを stdout または stderr に直接書き込むようにします。
• 行バッファリングを使用する:
  • パイプ処理を避けられない場合は、行バッファリングをサポートするツールを使用します。たとえば、grep --line-buffered を使用します。
  • カスタム アプリケーションの場合は、stdout に書き込むときに、ログを頻繁に（理想的には各行の後に）フラッシュするようにします。ロギング ライブラリの多くには、バッファリングを制御する設定があります。

• バッファリングの動作をテストする: 次の Pod マニフェストをデプロイし、kubectl logs -f buffered-pod コマンドを使用してログへの影響を確認します。buffered-container マニフェストでさまざまな command 配列をコメント化したり、コメント化を解除したりしてテストします。

  # buffered.yaml
  apiVersion: v1
  kind: ConfigMap
  metadata:
  name: run-script
  data:
  run.sh: |
      #!/bin/bash
      echo "Starting..."
      for i in $(seq 3600); do
      echo "Log ${i}"
      sleep 1
      done
      echo "Exiting."
  ---
  apiVersion: v1
  kind: Pod
  metadata:
  name: buffered-pod
  spec:
  containers:
      - name: buffered-container
      image: ubuntu  # Or any other image with bash
  
      # Case 1: Direct execution - line buffered by default to TTY
      # Logs appear immediately.
      command: ['/bin/bash', '-c', '/mnt/run.sh']
  
      # Case 2: Piped to grep - fully buffered by default
      # Logs might be delayed or appear in chunks.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep Log']
  
      # Case 3: Piped to grep with --line-buffered
      # Logs appear immediately.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep --line-buffered Log']
  
      volumeMounts:
          - name: scripts
          mountPath: /mnt
  volumes:
      - name: scripts
      configMap:
          name: run-script
          defaultMode: 0777
  restartPolicy: Never
  

ログ エクスプローラのクエリを調査する

ログは間違いなく収集されているのに表示されない場合は、検索クエリまたは期間に問題がある可能性があります。

症状:

アプリケーションがログを確実に生成しているのに、想定されるログが検索結果に表示されない。

原因:

ログ エクスプローラのクエリに、目的のログが意図せず除外されるフィルタ（Namespace、ラベル、リソースタイプ、テキストなど）が含まれている可能性があります。

解決策:

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

2. [期間を選択] をクリックします。ログが発生した日時がわかっている場合でも、タイミングの問題を除外するために、はるかに長い期間を指定してみてください。

3. クエリを簡素化します。

   1. すべてのフィルタをクリアします。

   2. クラスタのみでフィルタしてみます。

      resource.type="k8s_container"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      

      次のように置き換えます。

      • CLUSTER_NAME: クラスタの名前。
      • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。

   3. [クエリを実行] をクリックします。

4. 広範囲のクエリが機能する場合は、元のフィルタを 1 つずつ再導入します。

   • リソースタイプ: 正しいリソースタイプを使用していることを確認します。たとえば、k8s_node でフィルタする必要がある場合に、k8s_container でフィルタしていないかどうかを確認します。
   • ラベル: namespace_name、container_name、カスタムラベルなどの resource.labels のスペルを再確認します。
   • 重大度: 重大度（severity=ERROR など）が過度に制限されていないことを確認します。
   • テキスト ペイロード: 検索キーワードのスペルミスや過度に制限する文字列を確認します。たとえば、完全一致の場合は「含む」を表すために = ではなく :（jsonPayload.message="error" ではなく jsonPayload.message:"error"）を使用します。

5. フィルタで大文字と小文字が区別されることを確認します（通常、テキストでは大文字と小文字が区別されませんが、ラベルでは区別される場合があります）。値に隠し文字や余分なスペースが含まれていないこと、特殊文字を含むキーワードを引用符で囲む必要がないかどうかを確認します。

6. [タイムライン] を確認します。フィルタを追加したときに急激な低下が見られる場合は、クエリの問題のある部分を特定できる可能性があります。

効果的なロギングクエリに関するその他のアドバイスについては、Cloud Logging ドキュメントのログエントリの迅速な検索をご覧ください。

クエリを変更してもログが表示されない場合は、クエリの問題ではなく、このドキュメントの他のセクションで説明されている問題である可能性があります。

アプリケーション固有のロギング動作を調査する

GKE Logging エージェントは、stdout ストリームと stderr ストリームに書き込まれたログのみを収集します。

症状:

クラスタの他のログは Cloud Logging に表示されるのに、特定の Pod またはコンテナのログが表示されない。

原因:

アプリケーションが stdout または stderr に書き込んでいません。ログをコンテナ内のファイルに書き込むように誤って構成されていて、Logging エージェントが収集できない可能性があります。

アプリケーションの出力で JSON テキストと JSON 以外のテキストが混在している可能性もあります。Logging エージェントのパーサーは、単一のストリームで一貫した形式（JSON またはテキスト）を想定しています。JSON ロギング用に構成されたアプリケーションが書式なしテキスト行を出力すると、パーサーが中断し、ログがドロップされるか正しく取り込まれない可能性があります。

解決策:

1. ログが取得されないアプリケーションの Pod 名と Namespace を確認します。

   kubectl get pods -n NAMESPACE_NAME
   

2. コンテナログを確認します。

   • Pod のコンテナが 1 つの場合は、次のコマンドを実行します。

     kubectl logs POD_NAME \
         -n NAMESPACE_NAME
     

     次のように置き換えます。

     • POD_NAME: Pod の名前。
     • NAMESPACE_NAME: Pod の Namespace。

   • Pod に複数のコンテナがある場合は、コンテナ名を指定します。

     kubectl logs POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     CONTAINER_NAME は、Pod 内のコンテナの名前に置き換えます。

   • ログをリアルタイムで追跡するには、次のコマンドを実行します。

     kubectl logs -f POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     次のように置き換えます。

     • POD_NAME: Pod の名前。
     • CONTAINER_NAME: Pod 内のコンテナの名前。
     • NAMESPACE_NAME: Pod の Namespace。

3. 出力を分析します。

   • kubectl logs コマンドの出力がない場合や、コマンド出力に想定されるログが含まれていない場合は、アプリケーション自体に問題があります。kubectl logs コマンドは、コンテナ ランタイムによってキャプチャされた stdout ストリームと stderr ストリームから直接読み取ります。ログがここにない場合、GKE の Logging エージェントはログを確認できません。

     アプリケーションのコードまたは構成を変更して、ファイルへの書き込みを停止し、代わりにすべてのメッセージを stdout（通常のログ用）と stderr（エラーログ用）に直接ロギングします。

   • JSON 文字列と書式なしテキスト行が混在している場合、この出力は形式が混在している問題を示しています。有効な単一行の JSON オブジェクトのみを stdout と stderr に書き込むようにアプリケーションを構成します。

   • kubectl logs コマンドを実行して、想定されるログが表示される場合は、ロギング パイプラインのさらに下流（エージェント、権限、Cloud Logging サービスなど）に問題がある可能性があります。

プラットフォームとサービスに関する問題のトラブルシューティング

以降のセクションでは、ログの保持ポリシー、Cloud Logging の健全性、サポートされていない GKE バージョンなど、直接の構成以外の問題の調査について説明します。

ログの保持期間を調査する

ログはバケットに保存されます。各バケットには、ログが自動的に削除されるまでの保持期間が設定されています。

症状:

特定の日付より古いログが表示されない。

原因:

目的のログが、転送先のログバケットの保持期間を経過しています。

解決策:

保持期間を特定して更新するには、次のいずれかのオプションを選択します。

コンソール

1. GKE ログが転送されるバケットを特定します。

   1. Google Cloud コンソールで、[ログルーター] ページに移動します。

      [ログルーター] に移動

   2. ログの転送先を示す [宛先] 列を確認します。

      宛先は次のようになります。

      logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
      

      PROJECT_ID、LOCATION、BUCKET_ID をメモします。

      ログは多くの場合、_Default バケットに転送されますが、カスタムシンクを構成している場合は、他のバケットに転送されることもあります。

2. ログバケットの保持期間を確認します。

   1. Google Cloud コンソールで、[ログストレージ] ページに移動します。

      [ログストレージ] に移動

   2. シンクの宛先から BUCKET_ID、LOCATION、PROJECT_ID に一致するバケットを見つけます。

   3. 関連する各バケットの [保持期間] 列を確認します。

   4. 目的のログが保持期間を経過している場合、それらのログは Cloud Logging によって削除されました。保持期間を延長する必要がある場合は、次の操作を行います。

      1. 保持期間を延長するバケットで、[ その他の操作] をクリックします。
      2. [バケットを編集] を選択し、保持期間を更新します。費用に影響する可能性があることに注意してください。

gcloud

1. GKE ログが転送されるバケットを特定します。

   gcloud logging sinks list --project=PROJECT_ID
   

   出力を確認します。各シンクの destination フィールドは、ログの転送先を示しています。ログバケットの宛先の形式は次のとおりです。

   logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
   

   PROJECT_ID、LOCATION、BUCKET_ID をメモします。

   ログは多くの場合、_Default バケットに転送されます。

2. ログバケットの保持期間を確認します。

   gcloud logging buckets describe BUCKET_ID \
       --location=LOCATION \
       --project=PROJECT_ID
   

   出力で retentionDays フィールドを探します。必要なログが retentionDays に表示されている値を経過している場合、それらのログは Cloud Logging によって削除されました。

3. 保持期間を延長する必要がある場合は、更新します。

   gcloud logging buckets update BUCKET_ID \
       --location=LOCATION \
       --retention-days=RETENTION_DAYS \
       --project=PROJECT_ID
   

   次のように置き換えます。

   • BUCKET_ID: ログバケットの ID。
   • LOCATION: バケットの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
   • RETENTION_DAYS: ログを保持する日数。保持期間を延長すると、費用に影響する可能性があることに注意してください。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

Cloud Logging サービスの問題と取り込みの遅延を調査する

ロギング パイプライン自体で、サービス全体の中断や一時的かつ大規模な取り込み遅延などの問題が発生することがあります。

症状:

• 複数のプロジェクトまたはクラスタでログの損失が広範囲または断続的に発生している。
• ログがログ エクスプローラに表示されるまでに大幅な遅延が発生する。

原因:

• Cloud Logging サービスが中断している: まれにサービス全体にわたる中断により、ログの取り込みが妨げられ、広範囲にわたる遅延やログの完全な損失が発生する可能性があります。
• ログの量が多い: 正式なサービス中断がなくても、プロジェクトまたはリージョンのログの量が多いと、取り込みサービスが一時的に過負荷になり、ログの表示が遅延することがあります。

解決策:

• Google CloudService Health ダッシュボードにアクセスして、 Google Cloud サービスのステータスを確認します。Cloud Logging または GKE に関連する対応待ちのインシデントがないかどうかを確認します。

• 取り込みの遅延の可能性を考慮します。ログがすぐに表示されず、アクティブなインシデントがない場合、特にログの量が多い場合は取り込みが完了するまでしばらく待ちます。数分後にもう一度確認してください。

クラスタ バージョンを調査する

GKE は、Logging エージェントなどのコンポーネントのバグの修正とパフォーマンスの改善を含む新しいバージョンを定期的にリリースします。

症状:

ロギングの問題がクラスタ バージョンの制限と一致する。

原因:

Logging エージェントの既知の問題があるか、特定のロギング機能がない古いバージョンまたはサポートされていないバージョンの GKE がクラスタで実行されている可能性があります。

解決策:

この問題を解決するには、次の操作を行います。

1. クラスタのバージョンを確認します。

   gcloud container clusters describe CLUSTER_NAME \
       --location LOCATION \
       --format="value(currentMasterVersion)"
   

   次のように置き換えます。

   • CLUSTER_NAME: クラスタの名前。
   • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。

2. サポートされているバージョンであることを確認するには、このバージョンを GKE リリース スケジュールと比較します。

3. クラスタでサポートされていないバージョンが使用されている場合は、クラスタをアップグレードします。

次のステップ

• このドキュメントで問題を解決できない場合は、サポートを受けるで、次のトピックに関するアドバイスなど、詳細なヘルプをご覧ください。

  • Cloud カスタマーケアに問い合わせて、サポートケースを登録する。
  • StackOverflow で質問する、google-kubernetes-engine タグを使用して類似の問題を検索するなどして、コミュニティからサポートを受ける。#kubernetes-engine Slack チャネルに参加して、コミュニティ サポートを利用することもできます。
  • 公開バグトラッカーを使用して、バグの報告や機能リクエストの登録を行う。