使用虚拟机扩展程序管理器政策安装和管理 Ops Agent

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

您可以使用 VM Extension Manager 政策在特定可用区内的一组 Compute Engine 虚拟机上安装和管理 Ops Agent。例如，您可以使用这些政策来执行以下任务：

• 在整个舰队范围内安装：在可用区中的所有虚拟机上安装 Ops Agent，或在可用区中通过标签标识的一组虚拟机上安装 Ops Agent。

• 版本控制：

  • 将 Ops Agent 保持在最新版本。
  • 将 Ops Agent 版本固定到特定版本。

• 配置管理：将自定义配置应用于由政策管理的所有虚拟机上的 Ops Agent。

借助虚拟机扩展程序管理器，您可以创建政策来声明要在虚拟机上安装哪些扩展程序。Ops Agent 是可用的扩展程序之一。如果 Ops Agent 是使用虚拟机扩展程序管理器安装的，则虚拟机扩展程序管理器政策可以管理 2.58.0 版或更高版本的 Ops Agent。这些政策无法管理低于 2.58.0 版的 Ops Agent 版本、通过其他方式安装的 Ops Agent 实例，或旧版 Monitoring 代理或 Logging 代理的任何版本。

您可以使用 Google Cloud 控制台或 Google Cloud CLI (gcloud) 创建和管理虚拟机扩展政策。

准备工作

在开始使用虚拟机扩展管理器扩展政策之前，请执行以下操作：

• 查看受支持的操作系统，验证您的操作系统是否支持 Ops Agent 和虚拟机扩展管理器。
• 授予使用虚拟机扩展程序管理器所需的角色。
• 如果您想使用命令行界面创建和管理扩展政策，请安装 Google Cloud CLI。
• 卸载虚拟机上已安装的所有可观测性代理。

查看支持的操作系统

在尝试使用虚拟机扩展程序管理器政策管理 Ops Agent 之前，请验证目标操作系统是否与 Ops Agent 和虚拟机扩展程序管理器都兼容。

虚拟机扩展程序管理器支持 Ops Agent 支持的所有操作系统，但 SUSE Linux Enterprise Server (SLES) 和 Ubuntu 除外。如需详细了解 Ops Agent 支持的操作系统，请参阅操作系统。

如果您的操作系统同时受 Ops Agent 和虚拟机扩展程序管理器支持，请继续阅读本文档的其余部分。

启用使用 Ops Agent 所需的 API

如需使用 Ops Agent 写入日志和指标，您必须在 Google Cloud 项目中启用 Cloud Logging API 和 Cloud Monitoring API。

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

授予使用 Ops Agent 所需的角色

如需获得使用 Ops Agent 写入日志和指标所需的权限，请让管理员为您授予服务账号的以下 IAM 角色：

• 写入日志：Logging Logs Writer (roles/logging.logWriter)
• 写入指标： Monitoring Metric Writer (roles/monitoring.metricWriter)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需详细了解角色和 Ops Agent，请参阅向 Ops Agent 授权。

授予使用虚拟机扩展程序管理器所需的角色

如需获得创建、查看、修改和删除虚拟机扩展政策所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• 创建扩展程序政策：VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• 如需查看扩展程序政策：
  • VM Extension Policy Viewer (roles/compute.vmExtensionPolicyViewer)
  • VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• 如需修改扩展政策： VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)
• 如需删除扩展程序政策，您需要具备以下权限： VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含创建、查看、修改和删除虚拟机扩展政策所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能创建、查看、修改和删除虚拟机扩展程序政策：

• 如需创建扩展程序政策，请执行以下操作： compute.vmExtensionPolicies.create
• 如需查看扩展程序政策： compute.vmExtensionPolicies.list
• 查看扩展程序政策的详细信息： compute.vmExtensionPolicies.get
• 如需修改扩展程序政策，请执行以下操作： compute.vmExtensionPolicies.update
• 如需删除扩展程序政策，请执行以下操作： compute.vmExtensionPolicies.delete

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解 Compute Engine 中的 IAM 角色和权限，请参阅 Compute Engine 角色和权限。

安装 Google Cloud CLI

您可以使用 Google Cloud 控制台或 Google Cloud CLI (gcloud) 创建和管理虚拟机扩展政策。如需使用 gcloud，您必须先执行以下步骤来安装它：

1. 如果您尚未安装 Google Cloud CLI，请进行安装。

   本文档中介绍的扩展程序政策使用 beta 命令组。

1. 如果您尚未安装 gcloud CLI 的 beta 组件，请运行以下命令进行安装：

   gcloud components install beta
   

   如需检查您是否安装了 beta 组件，请运行以下命令：

   gcloud components list
   

   如果您之前安装了 beta 组件，请验证您是否拥有最新版本：

   gcloud components update
   

卸载所有可观测性代理

在创建虚拟机扩展管理器政策以管理虚拟机上的 Ops Agent 之前，请确保虚拟机上没有 Ops Agent 或旧版 Monitoring 代理和 Logging 代理的实例。在同一虚拟机上运行 Ops Agent 和旧版代理可能会导致提取重复的日志或导致指标提取冲突。

如果您使用扩展政策在已安装其他可观测性代理的虚拟机上安装 Ops Agent，则该政策会安装代理，但由于检测到冲突，代理无法运行。

移除现有代理的方式取决于这些代理的安装方式。

• 由虚拟机管理器 OS Config 政策安装的代理，包括以下代理：

  • 在创建虚拟机期间使用 Google Cloud 控制台安装的 Ops Agent。
  • 由正式版 VM Manager OS Config 政策安装的 Ops Agent。
  • 通过 Beta 版虚拟机管理器 OS Config 政策安装的 Ops Agent 或旧版 Monitoring 代理或 Logging 代理。

  如需了解如何使用这些政策来识别虚拟机，请参阅查找 Ops Agent 操作系统政策涵盖的虚拟机。

  如需了解如何卸载代理和移除 OS Config 政策，请参阅在 Ops Agent 操作系统政策涵盖的虚拟机上卸载 Ops Agent。

• 使用安装脚本手动安装的代理。如需了解如何卸载代理，请参阅以下内容：

  • Ops Agent：卸载代理。
  • 旧版 Monitoring 代理：卸载代理。
  • 旧版 Logging 代理：卸载代理。

通过创建虚拟机扩展程序政策来安装 Ops Agent

创建虚拟机扩展政策，以便在 Compute Engine 虚拟机 (VM) 舰队中自动安装和管理 Ops Agent。通过定义政策，您可以确保在符合您指定条件的任何虚拟机（例如具有特定虚拟机标签的虚拟机）上安装并维护特定扩展程序（例如 Ops Agent）。

政策冲突和优先级

虚拟机扩展程序管理器会为每个新政策关联一个优先级，数字越小，优先级越高；默认优先级为 1000。一个虚拟机可以受多个扩展程序（例如 Ops Agent）政策的涵盖，但只有一个 Ops Agent 扩展程序政策对该虚拟机有效。

虚拟机扩展程序管理器使用优先级来解决应用于虚拟机的政策之间的冲突。如需详细了解解决流程，请参阅政策优先级和冲突解决。

在可用区中的所有虚拟机上安装最新版本的 Ops Agent

如需创建一项政策，以在可用区中的所有虚拟机上安装最新版本的 Ops Agent，并在发布新版本时更新 Ops Agent，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 点击 + 创建。
3. 在名称字段中，输入政策的名称。
4. 可选：在说明字段中，输入政策的说明。
5. 在优先级字段中，指定一个优先级编号，以解决政策之间的冲突。数字越小，优先级越高。默认值为 1000。

6. 在可用区列表中，选择要应用此政策的可用区。

7. 在管理扩展程序部分中，点击添加扩展程序，然后执行以下操作：

   1. 从扩展程序列表中，选择 Google Cloud's Extension for Ops Agent。
   2. 将版本字段留空。

8. 点击创建。

gcloud

使用以下 gcloud beta compute zone-vm-extension-policies create 命令创建政策：

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

gcloud beta compute zone-vm-extension-policies create 采用 --version 选项。 如果您省略 --version 选项，则政策会安装最新版本，并在有新版本发布时更新 Ops Agent。

将可用区中所有虚拟机上的 Ops Agent 固定到特定版本

如需创建一项政策，以在可用区中的所有虚拟机上安装特定版本的 Ops Agent，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 点击 + 创建。
3. 在名称字段中，输入政策的名称。
4. 可选：在说明字段中，输入政策的说明。
5. 在优先级字段中，指定一个优先级编号，以解决政策之间的冲突。数字越小，优先级越高。默认值为 1000。

6. 在可用区列表中，选择要应用此政策的可用区。

7. 在管理扩展程序部分中，点击添加扩展程序，然后执行以下操作：

   1. 从扩展程序列表中，选择 Google Cloud's Extension for Ops Agent。
   2. 从版本列表中，选择要安装的版本。 使用 2.58.0 或更高版本。

8. 点击创建。

gcloud

使用以下 gcloud beta compute zone-vm-extension-policies create 命令创建政策：

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent
  --version=ops-agent=VERSION

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

• VERSION：要安装的 Ops Agent 版本。 使用 2.58.0 或更高版本。

  如果您省略 --version 选项，则政策会安装最新版本，并在发布新版本时更新 Ops Agent，如安装最新版本的示例所示。

如需查看 Ops Agent 版本列表，请参阅 GitHub 上的 Ops Agent 发布页面。

在具有特定标签的可用区中的虚拟机上安装 Ops Agent

如需创建一项政策，以在具有特定标签的可用区中的虚拟机上安装最新版本的 Ops Agent，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 点击 + 创建。
3. 在名称字段中，输入政策的名称。
4. 可选：在说明字段中，输入政策的说明。
5. 在优先级字段中，指定一个优先级编号，以解决政策之间的冲突。数字越小，优先级越高。默认值为 1000。

6. 在可用区列表中，选择要应用此政策的可用区。

7. 在扩展程序部分，点击添加扩展程序，然后执行以下操作：

   1. 从扩展程序列表中，选择 Google Cloud's Extension for Ops Agent。
   2. 将版本字段留空。

8. 在目标虚拟机实例部分中，选择要应用相应政策的虚拟机。如需选择具有特定标签的虚拟机，请点击添加标签，然后添加键值对。

9. 点击创建。

gcloud

使用 gcloud beta compute zone-vm-extension-policies create 命令的 --inclusion-labels 选项指定以英文逗号分隔的键值对列表：

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent
  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

• KEY1=VALUE1,KEY2=VALUE2：以英文逗号分隔的键值对列表，用于定义选择器的包含标签。虚拟机必须具有选择器中指定的所有标签（逻辑“与”）才能被纳入。如果您多次指定 --inclusion_labels 选项，则政策会以任何选择器中的所有标签为目标（逻辑 OR）。如果您省略此选项，则政策会以指定可用区中的所有虚拟机为目标。

在可用区中的所有虚拟机上安装具有自定义配置的 Ops Agent

如需创建一项政策，以在可用区中的所有虚拟机上安装最新版本的 Ops Agent，并为该 Ops Agent 提供自定义配置，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 点击 + 创建。
3. 在名称字段中，输入政策的名称。
4. 可选：在说明字段中，输入政策的说明。
5. 在优先级字段中，指定一个优先级编号，以解决政策之间的冲突。数字越小，优先级越高。默认值为 1000。

6. 在可用区列表中，选择要应用此政策的可用区。

7. 在扩展程序部分，点击添加扩展程序，然后执行以下操作：

   1. 从扩展程序列表中，选择 Google Cloud's Extension for Ops Agent。
   2. 将版本字段留空。
   3. 在配置文件内容字段中，输入 Ops Agent 的 YAML 配置字符串。

8. 点击创建。

gcloud

使用 gcloud beta compute zone-vm-extension-policies create 命令的 --config-from-file 选项指定配置文件：

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

• OPS_AGENT_CONFIG_PATH：包含 Ops Agent 的 YAML 配置字符串的文件的路径。 此文件必须存在于您运行 gcloud 命令的环境中。

  Ops Agent 的配置 YAML 可能很长。将配置放入文件中并将其传递给 gcloud CLI，比尝试在命令行中输入格式正确的 YAML 更不容易出错。在创建政策后更改此文件不会更新政策；如需更新政策，请使用 gcloud beta compute zone-vm-extension-policies update 命令。

如果您在创建或更新扩展政策时为 Ops Agent 提供自定义配置，则该政策会部署具有自定义配置的 Ops Agent。您无需手动重启代理。

配置会与扩展程序政策一起存储，因此请勿在配置中包含密码等敏感数据。由于配置与扩展程序政策一起存储，因此修改配置文件不会更改代理的配置。您必须使用 gcloud beta compute zone-vm-extension-policies update 命令更新存储在政策中的配置。

当您为 Ops Agent 提供自定义配置时，虚拟机扩展程序管理器会将该配置复制到目标虚拟机上供 Ops Agent 用于用户指定配置文件的位置：

• Linux：/etc/google-cloud-ops-agent/config.yaml
• Windows：C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

如果虚拟机上存在 config.yaml 文件，扩展程序政策会覆盖该文件。

如需了解有关如何使用Google Cloud 控制台和 gcloud CLI 创建虚拟机扩展政策的常规信息，请参阅 通过创建扩展政策来安装虚拟机扩展。

通过更新虚拟机扩展程序政策来管理 Ops Agent

如需更改政策管理 Ops Agent 的方式，请更新政策。 更新政策时，虚拟机扩展程序管理器通常会在一分钟内将更改部署到所有适用的虚拟机。如果您修改了包含标签，则系统可能会在新虚拟机上安装 Ops Agent，或者从现有虚拟机上卸载 Ops Agent，具体取决于虚拟机是否与更新后的标签匹配。

以下部分介绍了如何管理 Ops Agent 以执行以下操作：

• 更新可用区中所有虚拟机的已固定代理版本
• 修改可用区中所有虚拟机的 Ops Agent 配置

更新可用区中所有虚拟机的固定版 Ops Agent

如需更改可用区中所有虚拟机的已固定 Ops Agent 版本，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 选择要更新的政策。
3. 点击修改。
4. 在管理扩展程序部分中，执行以下操作：
   1. 选择 Google Cloud's Extension for Ops Agent。
   2. 修改版本字段。使用 2.58.0 或更高版本。
   3. 点击完成。
5. 点击保存。

gcloud

使用带有 --version 选项的 gcloud beta compute zone-vm-extension-policies update 命令修改固定的代理版本。

当您使用 gcloud 更新政策时，相应请求会完全替换现有政策。 您省略的任何可选字段都会恢复为默认值，而不是保留修改后的政策中的现有值。

如需通过政策更改可用区中所有虚拟机上安装的 Ops Agent 版本，请使用以下命令：

gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent
  --version=ops-agent=VERSION

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

• VERSION：要安装的 Ops Agent 版本。 使用 2.58.0 或更高版本。 如需查看版本列表，请参阅 GitHub 上的 Ops Agent 版本页面。

  如果您省略 --version 选项，则政策会安装最新版本，并在发布新版本时更新 Ops Agent，如安装最新版本的示例所示。

修改可用区中所有虚拟机上的 Ops Agent 配置

如需修改可用区中所有虚拟机的 Ops Agent 配置，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 选择要更新的政策。
3. 点击修改。
4. 在管理扩展程序部分中，执行以下操作：
   1. 选择 Google Cloud's Extension for Ops Agent。
   2. 修改配置文件内容字段。
   3. 点击完成。
5. 点击保存。

gcloud

将 gcloud beta compute zone-vm-extension-policies update 与 --config-from-file 选项或 --config 选项搭配使用，以指定新配置。

当您使用 gcloud 更新政策时，相应请求会完全替换现有政策。您省略的任何可选字段都会恢复为默认值，而不是保留修改后的政策中的现有值。

如需通过政策更改可用区中所有虚拟机上安装的 Ops Agent 的配置，请使用以下命令：

gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

• OPS_AGENT_CONFIG_PATH：包含 Ops Agent 的 YAML 配置字符串的文件的路径。 此文件必须存在于您运行 gcloud 命令的环境中。

  Ops Agent 的配置 YAML 可能很长。将配置放入文件中并将其传递给 gcloud CLI，比尝试在命令行中输入格式正确的 YAML 更不容易出错。

如果您在创建或更新扩展政策时为 Ops Agent 提供自定义配置，则该政策会部署具有自定义配置的 Ops Agent。您无需手动重启代理。

配置会与扩展程序政策一起存储，因此请勿在配置中包含密码等敏感数据。由于配置与扩展程序政策一起存储，因此修改配置文件不会更改代理的配置。您必须使用 gcloud beta compute zone-vm-extension-policies update 命令更新政策中存储的配置。

当您为 Ops Agent 提供自定义配置时，虚拟机扩展程序管理器会将该配置复制到目标虚拟机上供 Ops Agent 用于用户指定配置文件的位置：

• Linux：/etc/google-cloud-ops-agent/config.yaml
• Windows：C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

如果虚拟机上存在 config.yaml 文件，扩展程序政策会覆盖该文件。

如需了解有关使用Google Cloud 控制台和 gcloud CLI 管理虚拟机扩展政策的一般信息，请参阅通过更新虚拟机扩展政策来修改扩展。

通过删除虚拟机扩展程序政策来卸载 Ops Agent

如需卸载 Ops Agent，请删除管理该代理的虚拟机扩展程序政策。如果另一项有效且优先级较低的政策适用于某个虚拟机，并且也管理 Ops Agent，则该代理会根据优先级较低的政策继续安装在该虚拟机上。

在政策删除后的一分钟内，虚拟机扩展程序管理器会从所有可访问的虚拟机中移除 Ops Agent。如果虚拟机无法访问，虚拟机扩展程序管理器会跳过代理的删除操作。如果虚拟机再次可用，则 VM Extension Manager 会在此时移除代理。

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 选择要删除的政策。
3. 点击删除。
4. 在确认对话框中点击删除。

gcloud

如需删除用于管理 Ops Agent 的虚拟机扩展程序政策，请使用 gcloud beta compute zone-vm-extension-policies delete 命令：

gcloud beta compute zone-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

检索有关虚拟机扩展程序政策的信息

您可以检索有关现有虚拟机扩展程序政策的以下信息：

• Google Cloud 项目中的所有政策的列表。
• 有关特定政策的配置信息。

控制台

1. 在 Google Cloud 控制台中，前往扩展程序政策页面：

   前往扩展程序政策

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

   此页面列出了项目中的所有虚拟机扩展政策。
2. 如需查看特定扩展政策的详细信息，请点击相应政策的名称。

gcloud

列出虚拟机扩展程序政策

如需列出可用区中所有虚拟机扩展程序政策的相关信息，请使用 gcloud beta compute zone-vm-extension-policies list：

gcloud beta compute zone-vm-extension-policies list \
  --project=PROJECT_ID \
  --zone=ZONE \
  --page-size=PAGE_SIZE_INTEGER

替换命令中的以下变量：

• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。
• PAGE_SIZE_INTEGER：每页列出的政策数量，例如 2。如需详细了解排序和过滤选项，请参阅 gcloud beta compute zone-vm-extension-policies list。

描述已命名的虚拟机扩展程序政策

如需检索可用区中指定政策的配置，请使用 gcloud beta compute zone-vm-extension-policies describe：

gcloud beta compute zone-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

替换命令中的以下变量：

• POLICY_NAME：虚拟机扩展政策的名称。
• PROJECT_ID：项目的标识符。
• ZONE：目标可用区，例如 us-central1-f。

如需了解有关如何使用Google Cloud 控制台和 gcloud CLI 检索虚拟机扩展政策信息的常规信息，请参阅 查看扩展政策。

验证 Ops Agent 的安装

本部分介绍了如何执行以下操作：

• 验证 Ops Agent 安装的状态或版本
• 验证 Ops Agent 是否正在收集遥测数据

验证 Ops Agent 安装的状态或版本

如需确定 Ops Agent 的状态或版本，请使用以下某个Google Cloud 控制台页面：

Compute Engine

1. 在 Google Cloud 控制台中，前往虚拟机实例页面：

   前往虚拟机实例

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

2. 从列表中选择一个虚拟机。
3. 点击可观测性标签页。

Cloud Monitoring

1. 在 Google Cloud 控制台中，前往虚拟机实例页面：

   前往虚拟机实例

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 选择列表视图。

当 Ops Agent 已安装在虚拟机上并正在收集日志和指标时，Ops Agent 标签旁边会显示一个绿色对勾标记，表示代理的状态。

如需确定已安装的代理的版本，请将鼠标悬停在 Compute Engine 或 Monitoring 信息中心内的 Ops Agent 标签上。

验证 Ops Agent 是否正在收集遥测数据

如果 Ops Agent 已成功安装并正常运行，则会将指标发送到 Cloud Monitoring，并将日志发送到 Cloud Logging。

• 如需了解如何验证指标收集情况，请参阅代理在运行，但无法注入数据。
• 如需了解如何验证日志收集是否成功，请参阅验证是否成功收集了日志。

重启由扩展程序政策安装的 Ops Agent

当 Ops Agent 由 VM Extension Manager 安装和管理时，该代理不会由操作系统的系统管理服务（即 Linux 上的 systemd 或 Windows 上的 Windows 服务管理器）管理。因此，Linux systemctl 命令和 Windows *-Service 命令不适用于通过扩展政策安装的 Ops Agent。

如需重启通过扩展政策安装的 Ops Agent，请执行以下任一操作：

• 重新创建政策。

  1. 删除相应政策。删除政策会停止并卸载 Ops Agent。

  2. 创建新政策。新政策会安装并启动 Ops Agent。

• 使用临时的高优先级政策。如果原始政策影响大量虚拟机，但您只想在少量虚拟机上重启 Ops Agent，请向这些虚拟机添加标签，并将新政策配置为按标签进行过滤。

  例如，如果优先级为 1000 的政策未能启动虚拟机上的 Ops Agent，您可以向该虚拟机添加 status=failed 等标签。然后创建优先级更高的新政策，例如 500。例如，Google Cloud CLI 命令可能如下所示：

  gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
    --project=PROJECT_ID \
    --zone=ZONE \
    --extensions=ops-agent
    --inclusion-labels=status=failed \
    --priority=500 \
    --config-from-file=ops-agent=/usr/ops-agent-config.yaml
  

  替换命令中的以下变量：

  • POLICY_NAME：虚拟机扩展政策的名称。
  • PROJECT_ID：项目的标识符。
  • ZONE：目标可用区，例如 us-central1-f。

  新政策成功安装 Ops Agent 后，删除该政策并从虚拟机中移除相应标签。由于原始政策仍处于有效状态，因此 Ops Agent 仍安装在虚拟机上。

在虚拟机上启用客户机代理调试日志

VM Extension Manager 政策使用 Compute Engine 客机代理将 Ops Agent 作为虚拟机扩展程序进行管理。如需了解如何为客机代理启用调试日志记录，请参阅查看客机代理的调试日志。

排查扩展程序政策问题

本部分提供的信息可帮助您排查使用扩展政策管理 Ops Agent 时遇到的问题：

• gcloud beta compute zone-vm-extension-policies 命令失败
• 扩展程序政策已创建，但 Ops Agent 状态为“未检测到”
• Linux systemctl 和 Windows 服务管理器不适用于 Ops Agent

如需了解如何排查 Ops Agent 问题，请参阅排查 Ops Agent 问题。

gcloud beta compute zone-vm-extension-policies 命令失败

当 gcloud beta compute zone-vm-extension-policies 命令失败时，响应会包含问题排查建议。根据错误消息的建议，更正命令标志或实参中的任何错误。

如果命令的输出提及 IAM 权限不足，请查看授予使用虚拟机扩展程序管理器所需的角色中所述的必要角色和权限。

扩展程序政策已创建，但 Ops Agent 状态为“未检测到”

您已成功创建扩展程序政策，但 Ops Agent 在虚拟机上显示“未检测到”状态。

如果出现以下任一情况，Ops Agent 可能会显示为“未检测到”：

• 扩展程序政策无法安装 Ops Agent。
• 已安装的 Ops Agent 遇到阻止其运行的错误情况。

以下部分介绍了如何诊断这些情况。

验证 Ops Agent 是否已通过政策安装

VM Extension Manager 政策使用 Compute Engine 客机代理将 Ops Agent 作为虚拟机扩展程序进行管理。

如需确定 Ops Agent 是否由扩展程序政策安装，请使用以下任一方法查找来自 Guest 代理的日志条目：

日志浏览器

1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面：

   前往 Logs Explorer

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

2. 输入以下查询，然后点击运行查询：

   log_id("GCEGuestAgentManager")

Linux

在 Compute Engine 虚拟机上运行以下命令：

journalctl -u google-guest-agent-manager

Windows

在 Compute Engine 虚拟机上运行以下命令：

Get-Eventlog -Source google_guest_agent_manager -LogName Application

如果您看到包含 Failed to install plugin "ops-agent-plugin" ... 之类的字符串的日志，或者查询未返回任何日志，则表示扩展政策未能成功安装 Ops Agent。如需了解后续步骤，请参阅扩展政策无法安装 Ops Agent。

如果您看到包含 Successfully installed plugin "ops-agent_nnnnnnnn" 等字符串的日志，则表示扩展政策已成功安装 Ops Agent。如需了解后续步骤，请参阅已安装的 Ops Agent“未检测到”。

扩展程序政策无法安装 Ops Agent

如果存在以下任一情况，扩展政策可能无效：

• 虚拟机上未安装客户机代理。如需诊断和解决此问题，请执行以下操作：

  1. 验证虚拟机是否正在使用 Compute Engine 客机环境支持的操作系统。

  2. 查看虚拟机上安装的软件包，验证是否包含 google-guest-agent。

  3. 如果未安装 google-guest-agent，请安装客机代理。

• 已安装访客代理，但该代理已过时。如需诊断和解决此问题，请执行以下操作：

  1. 验证客机环境，以确定 google-guest-agent 软件包的版本。 虚拟机扩展程序管理器需要版本 20241209.01 或更高版本。

  2. 如果 google-guest-agent 的版本低于 20241209.01，请更新客机环境。

• 虚拟机扩展程序管理器不支持虚拟机的操作系统。如需了解详情，请参阅查看支持的操作系统。

已安装的 Ops Agent 的状态为“未检测到”

如果满足以下任一条件，Ops Agent 的状态可能为“未检测到”：

• 虚拟机上已安装可观测性代理。现有代理可能会导致冲突，必须将其卸载。如需了解详情，请参阅卸载所有可观测性代理。

  卸载之前安装的所有代理后，您可以重启 Ops Agent。

• Ops Agent 没有足够的权限将数据发送到 Cloud Logging 和 Cloud Monitoring。如需了解详情，请参阅遥测数据传输失败的常见原因。

验证 Ops Agent 配置是否有效

您通过创建或更新扩展政策为 Ops Agent 提供了自定义配置，但代理状态为“未检测到”。问题可能在于您的自定义配置存在错误。使用 guest 代理调试日志查找配置错误。

启用客机代理调试日志记录

如需了解如何为客机代理启用调试日志记录，请参阅查看客机代理的调试日志。

检查调试日志

日志浏览器

1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面：

   前往 Logs Explorer

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

2. 输入以下查询，然后点击运行查询：

   severity>=DEBUG log_id("GCEGuestAgentManager") "The agent config file is not valid"

Linux

在 Linux Compute Engine 虚拟机上运行以下命令：

journalctl -u google-guest-agent-manager | grep "The agent config file is not valid"

Windows

在 Windows Compute Engine 虚拟机上运行以下命令：

Get-Eventlog -Source google_guest_agent_manager -LogName Application | Where-Object {$_.Message -like "*The agent config file is not valid*"}

如果您看到包含字符串 The agent config file is not valid 的日志，则表示您在创建或更新扩展政策时为 Ops Agent 提供的自定义配置无效。

如需解决此问题，请执行以下操作：

• 请参阅配置 Ops Agent，更正配置。 有关 Ops Agent 配置文件结构的信息。

• 使用更正后的配置更新扩展程序政策。

Linux systemctl status 和 Windows Get-Service 命令不适用于 Ops Agent

您运行了类似 sudo systemctl status google-cloud-ops-agent"*" 的命令，但未返回任何信息。

当 Ops Agent 由 VM Extension Manager 安装和管理时，该代理不会由操作系统的系统管理服务（即 Linux 上的 systemd 或 Windows 上的 Windows 服务管理器）管理。

如需查找由虚拟机扩展程序管理器管理的 Ops Agent 的状态信息，请参阅以下内容：

• 代理健康检查
• 代理自身日志。

Linux systemctl restart 和 Windows Restart-Service 命令不适用于 Ops Agent

您运行了 sudo systemctl restart google-cloud-ops-agent 等命令，但 Ops Agent 未重启。

当 Ops Agent 由 VM Extension Manager 安装和管理时，该代理不会由操作系统的系统管理服务（即 Linux 上的 systemd 或 Windows 上的 Windows 服务管理器）管理。因此，您无法手动停止或启动 Ops Agent，并且以下命令不适用于 Ops Agent：

• Linux：sudo systemctl [stop|start|restart]
• Windows：Stop-Service、Start-Service、Restart-Service

如需停止或重启由虚拟机扩展程序管理器管理的 Ops Agent，您必须通过删除扩展程序政策来卸载该代理。如需详细了解如何停止或重启 Ops Agent，请参阅重启通过扩展政策安装的 Ops Agent。

其他问题排查信息

如需详细了解如何排查虚拟机扩展程序管理器政策的创建和使用问题，请参阅排查虚拟机扩展程序问题。

如需详细了解如何排查 Ops Agent 问题，请参阅排查 Ops Agent 问题。

配额

如需了解您可以在 Google Cloud 项目中创建的扩展政策数量，请参阅Quota。

价格

如需了解与使用虚拟机扩展程序管理器相关的费用，请参阅价格。

如果您安装 Ops Agent，则可能需要为代理发送到您的 Google Cloud 项目的指标、日志或跟踪记录付费。如需了解价格信息，请参阅 Google Cloud Observability 价格。

后续步骤

• 查看有关配置 Ops Agent 的详细信息。
• 详细了解虚拟机扩展程序管理器。