配置客机代理

本文档介绍了如何管理客机代理服务，以及如何通过修改其配置文件来配置其功能。

客机代理是客机环境的关键组件。客机环境包含实例在 Compute Engine 上运行时所需的脚本、守护程序和二进制文件。如需详细了解客机环境，请参阅客机环境。虽然客机代理默认情况下使用 Google 提供的操作系统映像中的默认设置，但您可能需要自定义其行为。如需详细了解客机代理的核心功能，请参阅客机代理功能。

重启客机代理

客机代理在 Linux 和 Windows 操作系统上均以守护进程的形式运行。在 Linux 上，客机代理以 systemd 服务的形式启动；在 Windows 上，它是系统服务。

Linux 和 Windows 操作系统之间的重启步骤有所不同，如下所示：

Linux

如需在 Linux 上重启，请选择以下选项之一：

  • 对于客机代理版本 20250901.00 或更高版本，请运行以下命令：

    ggactl_plugin coreplugin restart

  • 对于之前的客机代理版本，请运行以下命令：

    systemctl restart google-guest-agent

Windows

如需在 Windows 上重启，请选择以下选项之一：

  • 对于客机代理版本 20250901.00 或更高版本，请运行以下命令：

    ggactl_plugin coreplugin restart

  • 对于之前的客机代理版本，请使用以下 PowerShell 命令：

    1. 如需停止客机代理，请运行以下命令： 

      Stop-Service GCEAgent

    2. 如需启动客机代理，请运行以下命令： 

      Start-Service GCEAgent

    或者，如需重启客机代理，请运行以下命令： 

    Restart-Service GCEAgent

对于所有客机代理版本，您还可以使用任务管理器：找到 GCEGuestAgent 服务，然后重启该服务。

更新客机代理配置文件

您可以通过修改客机代理的配置文件 instance_configs.cfg 来自定义其行为。您可以通过此文件启用或停用功能，并为操作设置默认值。

如需在 Linux 和 Windows 操作系统上修改 instance_configs.cfg 文件，请参阅以下各部分。

Linux

如需在 Linux 虚拟机上修改配置文件，请执行以下操作：

  1. 创建或修改位于 /etc/default/instance_configs.cfg 的配置文件，并设置所需的选项。如需查看选项列表，请参阅配置选项。

    例如，如需自定义新用户的创建方式并指定要生成的 SSH 主机密钥类型，请创建或更新包含以下内容的文件：

    [Accounts]
useradd_cmd = useradd -m -G google-sudoers
[InstanceSetup]
host_key_types = ecdsa,ed25519

    注意：Linux 发行版可能会在 /etc/default/instance_configs.cfg.distro 中提供自己的默认设置。代理会先读取这些设置，但您在 /etc/default/instance_configs.cfg 中定义的任何设置都会替换发行版默认值。这样可确保在软件包更新期间不会丢失自定义配置。

  2. 修改配置文件后，重启客机代理以使更改生效。

Windows

在 Windows 虚拟机上，配置文件位于 C:\Program Files\Google\Compute Engine\instance_configs.cfg。如需详细了解如何在 Windows 上配置代理，请参阅启用和停用 Windows 实例功能。

配置选项

下表列出了 instance_configs.cfg 文件的可用配置选项。

账号

使用 instance_configs.cfg 文件的 Accounts 部分中的选项可控制客机代理的用户和群组管理。

选项 说明 操作系统 默认值
deprovision_remove 如果设置为 true，则在移除用户账号时，也会删除该用户的主目录。默认情况下，只有用户账号会被移除，而目录会保持不变。 Linux false
groups 新用户的群组的英文逗号分隔列表。 Linux 空
useradd_cmd 设置在创建新用户时客机代理所运行的命令。例如，如需创建用户的主目录并将用户添加到 google-sudoers 群组，请将该值设置为 useradd -m -G google-sudoers。 Linux 系统默认
userdel_cmd 设置在删除用户时客机代理所运行的命令。例如，如需移除用户的主目录和文件，请将该值设置为 userdel -r。 Linux 系统默认
usermod_cmd 设置在修改用户群组时客机代理所运行的命令。 Linux 系统默认
gpasswd_add_cmd 设置在将用户添加到群组时客机代理所运行的命令。 Linux 系统默认
gpasswd_remove_cmd 设置在从群组中移除用户时客机代理所运行的命令。 Linux 系统默认
groupadd_cmd 设置在创建新群组时客机代理所运行的命令。 Linux 系统默认

核心

使用 instance_configs.cfg 文件的 Core 部分中的选项可控制客机代理的核心功能。

选项 说明 操作系统 默认值
cloud_logging_enabled 如果设置为 false，客机代理不会将活动日志发送到 Cloud Logging。 Linux 和 Windows true
log_level 设置客机代理日志的日志记录级别。此设置会应用于客机代理生成的所有日志，而不仅仅是 Cloud Logging。设置和级别如下：
  • 0 (FATAL)：记录导致代理停止的严重错误。
  • 1 (ERROR)：记录可能会阻止代理运行的错误。
  • 2 (WARN)：记录可能有害的状况。
  • 3 (INFO)：记录有关代理活动的参考消息。这是默认设置。
  • 4 (DEBUG)：记录调试信息。此信息可能非常详细，但您可以使用 log_verbosity 选项来降低详细程度级别。
 Linux 和 Windows 3
log_verbosity 为 DEBUG 日志设置日志记录详细程度级别。可接受的值介于 0 到 4 之间。值越高，响应就越详细。 Linux 和 Windows 0

守护程序

使用 instance_configs.cfg 文件的 Daemons 部分中的选项可启用或停用由客机代理管理的特定后台守护程序。

选项 说明 操作系统 默认值
accounts_daemon 如果设置为 false，客机代理会停用用户账号和 SSH 密钥管理。 Linux true
clock_skew_daemon 如果设置为 false，客机代理会停用时钟同步。 Linux true
network_daemon 如果设置为 false，客机代理会停用网络管理。 Linux true

实例设置

使用 instance_configs.cfg 文件的 InstanceSetup 部分中的选项可控制在初始实例设置期间由客机代理执行的各种任务。

选项 说明 操作系统 默认值
host_key_types 要生成的主机密钥类型的英文逗号分隔列表。 Linux ecdsa,ed25519,rsa
optimize_local_ssd 如果设置为 false，客机在启动时不会优化本地 SSD。 Linux true
network_enabled 如果设置为 false，客机代理会跳过需要元数据信息的实例设置功能。将此选项设置为 false 还会停用主机密钥生成，并阻止客机代理配置 boto 配置文件。 Linux 和 Windows true
set_boto_config 如果设置为 false，客机代理不会创建或更新 boto 配置文件。如果不进行手动 boto 配置，使用 Boto 库并依赖默认客机代理配置来访问 Cloud Storage 的应用可能无法正常运行。 Linux 和 Windows true
set_host_keys 如果设置为 false，客机代理会在首次启动时跳过生成主机密钥的步骤。 Linux true
set_multiqueue 如果设置为 false，客机代理不会尝试通过为网络驱动程序启用多队列功能来优化网络性能。值为 true 时，代理会配置系统以使用多个队列处理网络流量，从而可能提高吞吐量并缩短延迟时间。 Linux true

IP 转发

使用 instance_configs.cfg 文件 IpForwarding 部分中的选项可配置客机代理管理 IP 转发和路由的方式。

选项 说明 操作系统 默认值
ethernet_proto_id 守护程序添加的路由的协议 ID 字符串。 Linux 66
ip_aliases 如果设置为 false，客机代理不会设置别名 IP 路由。 Linux true
target_instance_ips 如果设置为 false，客机代理不会启用内部 IP 地址负载均衡。 Linux true

元数据脚本执行

使用 instance_configs.cfg 文件 MetadataScripts 部分中的选项可控制元数据脚本（例如启动和关停脚本）的执行。

选项 说明 操作系统 默认值
default_shell 用于执行脚本的默认 shell。 Linux /bin/bash
run_dir 元数据脚本执行的基本目录。 Linux /var/run/google-startup-scripts
startup 如果设置为 false，客机代理不会运行来自元数据的启动脚本。 Linux 和 Windows true
shutdown 如果设置为 false，客机代理不会运行来自元数据的关停脚本。 Linux 和 Windows true

网络接口

使用 instance_configs.cfg 文件 NetworkInterfaces 部分中的选项可控制客机代理管理虚拟机上的网络接口的方式。

选项 说明 操作系统 默认值
setup 如果设置为 false，客机代理会跳过网络接口设置。 Linux true
ip_forwarding 如果设置为 false，客机代理会跳过 IP 转发。 Linux true
manage_primary_nic 如果设置为 true，客机代理会管理主 NIC 和次要 NIC。 Linux false
dhcp_command 用于启用网络接口的备用 DHCP 可执行文件的路径。 Linux 空
restore_debian12_netplan_config 如果设置为 true，客机代理会重新创建位于 /etc/netplan/90-default.yaml 的 Debian 12 默认 netplan 配置。 Linux (Debian 12) true

OS Login

使用 instance_configs.cfg 文件的 OSLogin 部分中的选项可配置客机代理与 OS Login 的集成。

选项 说明 操作系统 默认值
cert_authentication 如果设置为 false，则客机代理不会配置 sshd 的 TrustedUserCAKeys、AuthorizedPrincipalsCommand 和 AuthorizedPrincipalsCommandUser 密钥。 Linux true

后续步骤