使用扩展程序政策管理虚拟机扩展程序

虚拟机扩展程序管理器使用扩展程序政策大规模管理虚拟机扩展程序。如需了解详情，请参阅虚拟机扩展程序管理器简介。本文档介绍了如何查看、更新和删除虚拟机扩展程序政策。

IAM 角色和权限

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

查看扩展程序政策：
- 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.list
查看扩展程序政策的详细信息： compute.vmExtensionPolicies.get
修改扩展程序政策： compute.vmExtensionPolicies.update
删除扩展程序政策： compute.vmExtensionPolicies.delete

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

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

查看扩展程序政策

您可以使用 Google Cloud 控制台或 Google Cloud CLI 查看项目中的虚拟机扩展程序政策列表，也可以查看特定政策的详细信息。

控制台

在 Google Cloud 控制台中，前往虚拟机扩展程序政策页面。
前往“虚拟机扩展程序政策”
此页面列出了项目中的所有虚拟机扩展程序政策。
如需查看特定扩展程序政策的详细信息，请点击该政策的名称。

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

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目的 ID。
ZONE：您要列出其中的虚拟机扩展程序政策的可用区的名称。
PAGE_SIZE：每页返回的结果数上限。

如需查看特定扩展程序政策的详细信息，请使用 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：您的 Google Cloud 项目 ID。
ZONE：虚拟机扩展程序政策所在的 Google Cloud 可用区。

通过更新虚拟机扩展程序政策来修改扩展程序

更新政策时，虚拟机扩展程序管理器通常会在一分钟内将更改发布到所有适用的虚拟机。如果您修改了包含标签，则系统可能会在新虚拟机上安装扩展程序，或根据扩展程序是否与更新后的标签匹配，从现有虚拟机中卸载扩展程序。

控制台

在 Google Cloud 控制台中，前往虚拟机扩展程序政策页面。
前往“虚拟机扩展程序政策”
选择要更新的政策。
点击修改。
修改说明、优先级、扩展程序或目标虚拟机实例。
点击保存。

gcloud

使用 gcloud beta compute zone-vm-extension-policies update 命令修改现有虚拟机扩展程序政策。使用 gcloud 更新政策时，相应请求会完全替换现有政策。您省略的任何可选字段都会恢复为默认值，而不是保留修改后的政策中的现有值。

如需更新虚拟机扩展程序政策，请运行以下命令：

  gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
      --zone=ZONE \
      --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
      --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
      --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
      --inclusion-labels=KEY_1=VALUE_1 \
      --priority=PRIORITY_NUMBER \
      --description="DESCRIPTION"

替换以下内容：

POLICY_NAME：要更新的虚拟机扩展程序政策的名称。
ZONE：政策适用的 Google Cloud 可用区。
EXTENSION_NAME_1、EXTENSION_NAME_2：要更新的扩展程序的名称。您必须至少指定一个扩展程序。
VERSION_1：第一个虚拟机扩展程序的版本。
VERSION_2：第二个虚拟机扩展程序的版本。
EXTENSION_NAME_1=CONFIG_FILE_PATH_1、EXTENSION_NAME_2=CONFIG_FILE_PATH_2：以英文逗号分隔的键值对列表，其中键是扩展程序名称，值是该扩展程序的配置文件路径。此路径位于运行 gcloud 命令的虚拟机上，而不是在安装扩展程序的虚拟机上。

或者，如需以内嵌字符串的形式提供配置，请使用 --config 标志，而不是 --config-from-file，例如 EXTENSION_NAME_1="CONFIG_1"。您可以使用 --config-from-file 或 --config，但不能在同一命令中同时使用这两者。
KEY_1=VALUE_1：以英文逗号分隔的键值对列表，用于定义选择器的包含标签。虚拟机必须具有选择器中的所有指定标签才能成为目标。如果您多次指定 --inclusion-labels，则政策会以与所提供的任何选择器匹配的虚拟机为目标（逻辑 OR）。如果您省略此标志，则政策会以指定可用区中的所有虚拟机为目标。
PRIORITY_NUMBER：虚拟机扩展程序政策的优先级编号。
DESCRIPTION：虚拟机扩展程序政策的说明。

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

删除政策时，虚拟机扩展程序管理器会从该政策管理的任何虚拟机中卸载扩展程序。不过，如果另一项有效的较低优先级政策适用于某个虚拟机并声明了同一扩展程序，则该扩展程序会根据较低优先级政策继续安装在该虚拟机上。

虚拟机扩展程序管理器会在政策删除后一分钟内从所有可访问的虚拟机中移除扩展程序。如果由于客机代理被移除或虚拟机被删除而导致虚拟机无法访问，则虚拟机扩展程序管理器会跳过扩展程序的删除操作。如果此类虚拟机再次可用，虚拟机扩展程序管理器会在此时移除扩展程序。

控制台

在 Google Cloud 控制台中，前往虚拟机扩展程序政策页面。
前往“虚拟机扩展程序政策”
选择要删除的政策。
点击删除。
在确认对话框中点击删除。

gcloud

使用 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：您的 Google Cloud 项目的 ID。
ZONE：该政策所在的 Google Cloud 可用区。

排查虚拟机扩展程序问题

本部分介绍了如何排查虚拟机扩展程序的问题。

验证扩展程序是否已安装

您可以通过检查虚拟机上的以下项来验证扩展程序是否已安装：

连接到虚拟机并检查正在运行的进程。

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

扩展程序名称	扩展程序的进程名称
`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"

在 Linux 虚拟机上，针对 Ops Agent 运行 ps 命令的输出可能会显示如下所示的条目：

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

启用并查看客机代理日志。客机代理日志会显示扩展程序何时安装和启动。

以下示例展示了在安装 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-centrall-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. 为安装失败的虚拟机添加新标签。例如，添加标签 status=failed。
  2. 创建优先级更高的政策，以新标签为目标。例如，如果失败的原始政策的默认优先级为 1000，请创建优先级更高的政策，例如 500。
```
gcloud beta 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. 成功安装扩展程序后，删除临时政策并从虚拟机中移除标签。由于原始政策仍然有效，因此扩展程序仍处于已安装状态。

查看客机代理的调试日志

如需启用调试日志记录，请将日志级别和详细程度设置添加到客机代理配置文件的 Core 部分，如下所示：

Linux

打开位于 /etc/default/instance_configs.cfg 的客机代理配置文件。
将以下代码行添加到该文件中。如果 [Core] 部分已存在，请将 log_level 和 log_verbosity 设置添加到该部分。
```
[Core]
log_level = 4
log_verbosity = 4
```

通过运行以下命令重启客机代理管理器。

 sudo systemctl restart google-guest-agent-manager

如需在扩展程序安装期间查看客机代理活动的日志，请运行以下命令：
```
journalctl -u google-guest-agent-manager
```

Windows

打开位于 C:\Program Files\Google\Compute Engine\instance_configs.cfg 的客机代理配置文件。
将以下代码行添加到该文件中。如果 [Core] 部分已存在，请将 log_level 和 log_verbosity 设置添加到该部分。
```
[Core]
log_level = 4
log_verbosity = 4
```
通过以 Windows 管理员身份运行以下命令，重启客机代理管理器：
```
 net stop GCEAgentManager
 net start GCEAgentManager
```
如需在扩展程序安装期间查看客机代理活动的日志，请在 PowerShell 中运行以下命令：
```
Get-Eventlog -Source google_guest_agent_manager -LogName Application
```

启用调试日志后，请检查以下常见错误：

磁盘空间不足：如果日志报告磁盘可用空间不足，请释放磁盘上的空间或调整磁盘大小以添加更多空间。
资源使用过度：如果日志表明客机代理因内存或 CPU 使用过度而停止了扩展程序，请将虚拟机的机器类型更改为具有更多资源的机器类型。

后续步骤

详细了解虚拟机扩展程序管理器。

使用扩展程序政策管理虚拟机扩展程序 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

IAM 角色和权限

所需权限

查看扩展程序政策

控制台

gcloud

通过更新虚拟机扩展程序政策来修改扩展程序

控制台

gcloud

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

控制台

gcloud

排查虚拟机扩展程序问题

验证扩展程序是否已安装

Linux

Windows

排查安装问题

查看客机代理的调试日志

Linux

Windows

后续步骤

使用扩展程序政策管理虚拟机扩展程序