排查虚拟机扩展程序问题

本文档介绍了如何在 Compute Engine 虚拟机 (VM) 实例上验证虚拟机扩展程序安装、诊断政策发布和虚拟机扩展程序状态问题，以及查看客机代理调试日志。按照以下说明，您可以找出预期扩展程序未安装、意外扩展程序在虚拟机上运行或扩展程序进程停止的原因。

准备工作

在排查虚拟机上的虚拟机扩展程序问题之前，请先完成以下前提条件：

• 确认您拥有检查扩展程序政策、虚拟机扩展程序管理器支持的扩展程序的元数据以及整个 Google Cloud 资源层次结构中的虚拟机扩展程序状态所需的权限。如需了解详情，请参阅查看虚拟机扩展程序详细信息和状态。
• 如需在连接到各个虚拟机之前识别安装失败、崩溃或回滚，请在 Cloud Logging 中查看历史扩展程序强制执行事件。如需了解详情，请参阅查看虚拟机扩展程序日志。
• 如需直接在虚拟机上检查正在运行的扩展程序进程和客机代理调试日志，请确认您可以使用 SSH 或 RDP 连接到虚拟机。

验证是否已安装扩展程序

如需确认 Compute Engine 虚拟机上是否已安装并运行扩展程序，请使用只读方法检查虚拟机扩展程序状态。仅在需要客机操作系统进程或日志详细信息时才连接到虚拟机。

使用只读方法检查虚拟机扩展程序状态

如需在不连接到虚拟机的情况下检查已安装扩展程序的运行时状态和健康状态，请运行 gcloud beta compute instances list-vm-extension-states 或 gcloud beta compute instances get-vm-extension-state 命令，或调用等效的 REST API 方法。响应会返回每个扩展程序的有效版本、强制执行状态 (enforcementState)、健康状态 (healthStatus)、诊断消息 (healthMsg) 和管理政策 ID (policyId)。如需了解详情，请参阅查看实例上的虚拟机扩展程序状态。

检查虚拟机上正在运行的扩展程序进程

如果远程状态查询未返回预期状态，请连接到虚拟机，并检查扩展程序进程是否在客机操作系统中运行。

下表列出了每个受支持扩展程序的进程名称：

扩展程序名称	扩展程序的进程名称
google-cloud-sap-extension	google_cloud_sap_agent
google-cloud-workload-extension	google_cloud_workload_agent
ops-agent	ops_agent

如需检查扩展程序进程是否正在虚拟机上运行，请选择您的操作系统：

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 虚拟机上运行时 ps 命令的输出示例：

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

查看客机代理安装条目

如需确认客机代理何时下载、提取和启动扩展程序插件，请启用并查看客机代理的调试日志。

以下代码段展示了客机代理在 Linux 虚拟机上安装并启动 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"

排查安装问题

如果虚拟机上未安装扩展程序，或者虚拟机上运行了非预期的扩展程序，请先诊断政策发布、目标标签和强制执行状态，然后再重试安装。

如需确定扩展程序无法在虚拟机上安装的原因，请完成以下诊断步骤：

1. 等待政策生效。政策发布（包括重试）最长可能需要 1 小时才能在目标虚拟机上完成。如需详细了解如何检查发布进度，请参阅查看扩展程序政策。
2. 检查您在政策中指定的包含标签是否与虚拟机上的标签匹配，并验证虚拟机扩展程序管理器支持的扩展程序的元数据：
   • 如需查看整个组织、文件夹或项目中的政策标签选择器和优先级编号，请参阅查看扩展政策。
   • 如需查看虚拟机扩展程序管理器在所有可用区或特定可用区中支持的扩展程序的名称、版本号和支持级别，请参阅查看虚拟机扩展程序和版本。
3. 如需查看强制执行状态、运行状况、诊断消息和治理政策 ID (policyId)，请检查受影响虚拟机上的扩展程序状态。常见的错误状态包括 INSTALL_FAILED、INCOMPATIBLE 和 ROLLED_BACK。当多项政策以同一虚拟机为目标时，policyId 字段会显示每项政策分别控制哪些扩展程序。如需了解详情，请参阅查看实例上的虚拟机扩展程序状态。
4. 如需找出虚拟机上的客机级安装错误，请为客机代理启用并查看调试日志。

重新尝试安装扩展程序

修复底层政策配置或客机操作系统问题后，请重新应用政策配置，以便客机代理在受影响的虚拟机上重试安装。

如需重试扩展程序安装，请选择以下选项之一：

• 重新创建政策：删除政策，然后创建新政策。

• 应用临时高优先级政策：如需在特定虚拟机上重试安装，而无需重新创建影响大型机群的政策，请完成以下步骤：

  1. 添加临时标签（例如 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. 客机代理在目标虚拟机上安装扩展程序后，删除临时政策。

  4. 从虚拟机中移除临时标签。由于原始政策仍会管理这些虚拟机，因此扩展程序仍会保持安装状态。

查看客机代理的调试日志

如果远程状态查询和 Logging 事件日志未显示扩展程序无法下载或启动的原因，请在客机代理配置文件的 Core 部分中启用详细调试日志记录。

如需为客机代理启用和查看调试日志，请选择您的操作系统：

Linux

如需在 Linux 虚拟机上启用调试日志记录，请完成以下步骤：

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 虚拟机上启用调试日志记录，请完成以下步骤：

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
   

解决常见的客机代理日志错误

检查客机代理调试日志时，请检查是否存在导致扩展程序无法在虚拟机上提取或运行的资源限制错误。

下表列出了客机代理调试日志中报告的常见错误以及解决方法：

错误条件	解决方法
磁盘可用空间不足	如果日志报告虚拟机没有足够的磁盘空间来下载或解压缩扩展程序归档文件，请删除未使用的文件或调整启动磁盘的大小。
资源用量过高	如果日志表明客机代理因内存或 CPU 使用率过高而停止了扩展程序，请将虚拟机的机器类型更改为具有更多内存或 vCPU 的机器类型。

后续步骤

• 如需检查发布进度和扩展程序运行状况，请参阅查看虚拟机扩展程序详细信息和状态。
• 如需在 Logging 中查询历史强制执行事件和审核安装，请参阅查看虚拟机扩展程序日志。
• 如需构建 Cloud Monitoring 信息中心并针对代理健康状况、CPU 和内存用量设置提醒，请参阅监控虚拟机扩展程序。
• 如需修改配置设置、更改固定版本或移除已部署的代理，请参阅使用扩展程序政策管理虚拟机扩展程序。