VM 拡張機能のトラブルシューティング

このドキュメントでは、Compute Engine 仮想マシン（VM）インスタンスで VM 拡張機能のインストールを確認する方法、ポリシーのロールアウトと VM 拡張機能の状態に関する問題を診断する方法、ゲスト エージェントのデバッグログを表示する方法について説明します。次の手順に沿って、想定される拡張機能がインストールされなかった理由、予期しない拡張機能が VM で実行されている理由、拡張機能プロセスが停止した理由を特定します。

始める前に

VM で VM 拡張機能の問題をトラブルシューティングする前に、次の前提条件を満たしてください。

  • 拡張機能ポリシー、VM Extension Manager がサポートする拡張機能のメタデータ、 Cloud de Confiance by S3NS リソース階層全体の VM 拡張機能の状態を検査するために必要な権限があることを確認します。詳細については、VM 拡張機能の詳細とステータスを表示するをご覧ください。
  • 個々の VM に接続する前に、インストールの失敗、クラッシュ、ロールバックを特定するには、Cloud Logging で過去の拡張機能の適用イベントを確認します。詳細については、VM 拡張機能のログを表示するをご覧ください。
  • VM で実行中の拡張機能プロセスとゲスト エージェントのデバッグログを直接検査するには、SSH または RDP を使用して VM に接続できることを確認します。

拡張機能がインストールされていることを確認する

Compute Engine VM に拡張機能がインストールされ、実行されているかどうかを確認するには、読み取り専用メソッドを使用して VM 拡張機能の状態を検査します。ゲスト OS のプロセスまたはログの詳細が必要な場合にのみ、VM に接続します。

読み取り専用メソッドを使用して VM 拡張機能の状態を検査する

VM に接続せずに、インストールされている拡張機能のランタイム状態と健全性ステータスを確認するには、gcloud beta compute instances list-vm-extension-states コマンドまたは gcloud beta compute instances get-vm-extension-state コマンドを実行するか、同等の REST API メソッドを呼び出します。レスポンスには、各拡張機能のアクティブなバージョン、適用状態（enforcementState）、健全性ステータス（healthStatus）、診断メッセージ（healthMsg）、管理ポリシー ID（policyId）が返されます。詳細については、インスタンスの VM 拡張機能の状態を表示するをご覧ください。

VM で実行中の拡張機能プロセスを検査する

リモート状態クエリで想定されるステータスが返されない場合は、VM に接続して、拡張機能プロセスがゲスト オペレーティング システムで実行されているかどうかを確認します。

次の表に、サポートされている拡張機能のプロセス名を示します。

拡張機能名 拡張機能のプロセス名
google-cloud-sap-extension google_cloud_sap_agent
google-cloud-workload-extension google_cloud_workload_agent
ops-agent ops_agent

拡張機能プロセスが VM で実行されているかどうかを確認するには、オペレーティング システムを選択します。

Linux

実行中の拡張機能プロセスを一覧表示するには、次のコマンドを実行します。

ps aux | grep 'EXTENSION_PROCESS_NAME'
 EXTENSION_PROCESS_NAME は、前の表の拡張機能のプロセス名に置き換えます。たとえば、ops-agent 拡張機能プロセスを一覧表示するには、次のコマンドを実行します。
ps aux | grep 'ops_agent'

Windows

実行中の拡張機能プロセスを一覧表示するには、次のコマンドを実行します。

tasklist | findstr "EXTENSION_PROCESS_NAME"
 EXTENSION_PROCESS_NAME は、前の表の拡張機能のプロセス名に置き換えます。たとえば、ops-agent 拡張機能プロセスを一覧表示するには、次のコマンドを実行します。
tasklist | findstr "ops_agent"

次のスニペットは、ops-agent 拡張機能が Linux VM で実行されている場合の ps コマンドの出力例を示しています。

....
/var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3
....

ゲスト エージェントのインストール エントリを確認する

ゲスト エージェントが拡張機能プラグインをダウンロード、抽出、起動した日時を確認するには、ゲスト エージェントのデバッグログを有効にして表示します。

次のスニペットは、ゲスト エージェントが Linux VM に ops-agent 拡張機能をインストールして起動したときのゲスト エージェントのログエントリの例を示しています。

my-instance google_guest_agent [14972]: Installing plugin "ops-agent", revision "2dfa648c1892da87"
my-instance google_guest_agent [14972]: (client.go:181) Sent message [[type.googleapis.com/agent_controlplane.PluginEventMessage: (revision_id:"2dfa648c1892da87)]]
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-central1-a/ops-agent
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "UnpackPluginArchiveStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:361) Successfully unpacked "/var/lib/google-guest-agent/ops-agent.tar.gz" to "/google-guest-agent/ops-agent_2dfa648c1892da87
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)
my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent 2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

インストールに関する問題のトラブルシューティング

VM に拡張機能がインストールされていない場合や、予期しない拡張機能が VM で実行されている場合は、ポリシーのロールアウト、ターゲット ラベル、適用状態を診断してから、インストールを再試行します。

VM に拡張機能をインストールできなかった理由を特定するには、次の診断手順を完了します。

  1. ポリシーの適用を待ちます。ポリシーのロールアウト（再試行を含む）がターゲット VM 全体で完了するまでに、最大 1 時間かかることがあります。ロールアウトの進行状況の確認の詳細については、拡張機能ポリシーを表示するをご覧ください。
  2. ポリシーで指定した包含ラベルが VM のラベルと一致することを確認し、VM Extension Manager がサポートする拡張機能のメタデータを確認します。
    • 組織、フォルダ、プロジェクト全体のポリシーラベル セレクタと優先度番号を確認するには、拡張ポリシーを表示するをご覧ください。
    • VM Extension Manager がすべてのゾーンまたは特定のゾーンでサポートしている拡張機能の名前、バージョン番号、サポートレベルを確認するには、VM 拡張機能とバージョンを表示するをご覧ください。
  3. 適用状態、健全性ステータス、診断メッセージ、管理ポリシー ID（policyId）を確認するには、影響を受ける VM の拡張機能の状態を検査します。一般的なエラー状態には、INSTALL_FAILED、INCOMPATIBLE、ROLLED_BACK などがあります。複数のポリシーが同じ VM をターゲットにしている場合、policyId フィールドには、各拡張機能を管理するポリシーが表示されます。詳細については、インスタンスの VM 拡張機能の状態を表示するをご覧ください。
  4. VM でゲストレベルのインストール エラーを特定するには、ゲスト エージェントのデバッグログを有効にして表示します。

拡張機能のインストールを再試行する

基盤となるポリシー構成またはゲスト OS の問題を修正したら、ポリシー構成を再適用して、ゲスト エージェントが影響を受ける VM へのインストールを再試行するようにします。

拡張機能のインストールを再試行するには、次のいずれかのオプションを選択します。

  • ポリシーを再作成する: ポリシーを削除してから、新しいポリシーを作成します。

  • 一時的に優先度の高いポリシーを適用する: 大規模なフリートに影響するポリシーを再作成せずに、特定の VM でインストールを再試行するには、次の手順を完了します。

    1. インストールに失敗した VM に status=failed などの一時的なラベルを追加します。

    2. 一時ラベルをターゲットとする優先度の高い（整数値が小さい）一時ポリシーを作成します。たとえば、元のポリシーでデフォルトの優先度 1000 が使用されている場合に、優先度 500 の一時ポリシーを作成するには、次のコマンドを実行します。

      gcloud compute zone-vm-extension-policies create temp-policy \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --priority=500 \
    --inclusion-labels=status=failed

    3. ゲスト エージェントがターゲット VM に拡張機能をインストールしたら、一時ポリシーを削除します。

    4. VM から一時ラベルを削除します。元のポリシーが引き続きこれらの VM を管理しているため、拡張機能はインストールされたままになります。

ゲスト エージェントのデバッグログを表示する

リモート状態クエリと Logging イベントログに、拡張機能のダウンロードまたは起動に失敗した理由が表示されない場合は、ゲスト エージェント構成ファイルの Core セクションで詳細なデバッグ ロギングを有効にします。

ゲスト エージェントのデバッグログを有効にして表示するには、オペレーティング システムを選択します。

Linux

Linux VM でデバッグ ロギングを有効にするには、次の手順を行います。

  1. /etc/default/instance_configs.cfg にあるゲスト エージェントの構成ファイルを開きます。

  2. /etc/default/instance_configs.cfg に次の設定を追加します。[Core] セクションがすでに存在する場合は、[Core] の下に log_level と log_verbosity を追加します。

    [Core]
log_level = 4
log_verbosity = 4

  3. ゲスト エージェント マネージャーを再起動するには、次のコマンドを実行します。

    sudo systemctl restart google-guest-agent-manager

  4. 拡張機能のインストール中に生成されたゲスト エージェント ログを表示するには、次のコマンドを実行します。

    journalctl -u google-guest-agent-manager

Windows

Windows VM でデバッグ ロギングを有効にするには、次の手順を行います。

  1. C:\Program Files\Google\Compute Engine\instance_configs.cfg にあるゲスト エージェントの構成ファイルを開きます。

  2. instance_configs.cfg に次の設定を追加します。[Core] セクションがすでに存在する場合は、[Core] の下に log_level と log_verbosity を追加します。

    [Core]
log_level = 4
log_verbosity = 4

  3. 昇格したコマンド プロンプトまたは PowerShell ウィンドウで、次のコマンドを実行してゲスト エージェント マネージャーを再起動します。

    net stop GCEAgentManager
net start GCEAgentManager

  4. PowerShell で、拡張機能のインストール中に生成されたゲスト エージェントのログを表示するには、次のコマンドを実行します。

    Get-Eventlog -Source google_guest_agent_manager -LogName Application

一般的なゲスト エージェント ログエラーを解決する

ゲスト エージェントのデバッグログを検査するときは、拡張機能が VM で抽出または実行されないようにするリソース制約エラーを確認します。

次の表に、ゲスト エージェントのデバッグログに記録される一般的なエラーとその解決方法を示します。

エラー条件 解決策
ディスク容量が不足しています 拡張機能アーカイブをダウンロードまたは抽出するための十分なディスク容量が VM にないことがログに記録されている場合は、未使用のファイルを削除するか、ブートディスクのサイズを変更します。
リソースの過剰使用 メモリまたは CPU の使用率が高いためにゲスト エージェントが拡張機能を停止したことがログに示されている場合は、VM のマシンタイプを変更して、メモリまたは vCPU の多いマシンタイプに変更します。

次のステップ