Configura el agente de invitado

En este documento, se describe cómo administrar el servicio del agente invitado y configurar sus funciones editando su archivo de configuración.

El agente invitado es un componente fundamental del entorno invitado. El entorno de invitado contiene secuencias de comandos, daemons y objetos binarios que las instancias necesitan para ejecutarse en Compute Engine. Para obtener más información sobre el entorno invitado, consulta Entorno invitado. Si bien el agente invitado funciona de forma predeterminada con la configuración predeterminada en las imágenes de SO proporcionadas por Google, es posible que desees personalizar su comportamiento. Para obtener más información sobre las funciones principales del agente invitado, consulta Funcionalidad del agente invitado.

Reinicia el agente de invitado

El agente invitado se ejecuta como un daemon en los sistemas operativos Linux y Windows. En Linux, el agente invitado se inicia como un servicio systemd, y en Windows, es un servicio del sistema.

Los pasos para reiniciar varían entre los sistemas operativos Linux y Windows de la siguiente manera:

Linux

Para reiniciar en Linux, elige una de las siguientes opciones:

  • Para la versión 20250901.00 o posterior del agente invitado, ejecuta el siguiente comando:

    ggactl_plugin coreplugin restart

  • Para versiones anteriores del agente invitado, ejecuta el siguiente comando:

    systemctl restart google-guest-agent

Windows

Para reiniciar en Windows, elige una de las siguientes opciones:

  • Para la versión 20250901.00 o posterior del agente invitado, ejecuta el siguiente comando:

    ggactl_plugin coreplugin restart

  • Para versiones anteriores del agente invitado, usa los siguientes comandos de PowerShell:

    1. Para detener el agente invitado, sigue estos pasos: 

      Stop-Service GCEAgent

    2. Para iniciar el agente invitado, sigue estos pasos: 

      Start-Service GCEAgent

    Como alternativa, para reiniciar el agente invitado, haz lo siguiente: 

    Restart-Service GCEAgent

En todas las versiones del agente invitado, también puedes usar el Administrador de tareas: busca el servicio GCEGuestAgent y, luego, reinícialo.

Actualiza el archivo de configuración del agente invitado

Para personalizar el comportamiento del agente invitado, edita su archivo de configuración, instance_configs.cfg. Este archivo te permite habilitar o inhabilitar funciones, y establecer valores predeterminados para las operaciones.

Para editar el archivo instance_configs.cfg en los sistemas operativos Linux y Windows, consulta las siguientes secciones.

Linux

Para editar el archivo de configuración en una VM de Linux, haz lo siguiente:

  1. Crea o edita el archivo de configuración ubicado en /etc/default/instance_configs.cfg y establece la opción requerida. Para obtener una lista de opciones, consulta Opciones de configuración.

    Por ejemplo, para personalizar cómo se crean los usuarios nuevos y especificar qué tipos de claves de host SSH se deben generar, crea o actualiza el archivo con el siguiente contenido:

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

  2. Después de modificar el archivo de configuración, reinicia el agente invitado para que se apliquen los cambios.

Precedencia del archivo de configuración

El agente invitado lee los parámetros de configuración de /etc/default/instance_configs.cfg y sus variantes .distro y .template. Estos archivos se procesan en una jerarquía específica para permitir que los usuarios y las distribuciones de Linux establezcan valores predeterminados. El orden de precedencia, de mayor a menor, es el siguiente:

  1. /etc/default/instance_configs.cfg.template (prioridad más alta)
  2. /etc/default/instance_configs.cfg.distro
  3. /etc/default/instance_configs.cfg (prioridad más baja)

Por ejemplo, puedes definir valores predeterminados en el archivo .template que anulen la configuración base de la distribución de Linux y del paquete del agente invitado.

Windows

En las VMs de Windows, el archivo de configuración se encuentra en C:\Program Files\Google\Compute Engine\instance_configs.cfg. Para obtener detalles sobre la configuración del agente en Windows, consulta Cómo habilitar y, luego, inhabilitar funciones de instancias de Windows.

Opciones de configuración

En las siguientes tablas, se enumeran las opciones de configuración disponibles para el archivo instance_configs.cfg.

Cuentas

Usa las opciones de la sección Accounts del archivo instance_configs.cfg para controlar la administración de usuarios y grupos por parte del agente invitado.

Opción Descripción Sistema operativo Valor predeterminado
deprovision_remove Si se configura como true, el agente invitado quita la cuenta de usuario cuando desaprovisionas a un usuario. De forma predeterminada (si se establece en false), el agente invitado solo quita al usuario del grupo google-sudoers y borra sus claves SSH, pero no quita la cuenta de usuario. Linux false
groups Es una lista separada por comas de los grupos para los usuarios nuevos. Linux adm,dip,docker,lxd,plugdev,video
useradd_cmd Establece el comando que ejecuta el agente invitado cuando se crea un usuario nuevo. Por ejemplo, para crear el directorio principal de un usuario y agregarlo al grupo google-sudoers, establece el valor en useradd -m -G google-sudoers. Linux Predeterminado
userdel_cmd Especifica el comando que ejecuta el agente invitado para borrar un usuario cuando deprovision_remove es true. Por ejemplo, establece esta opción en userdel -r para quitar el directorio principal y los archivos del usuario. Linux Predeterminado
usermod_cmd Establece el comando que ejecuta el agente invitado cuando se modifican los grupos de un usuario. Linux Predeterminado
gpasswd_add_cmd Establece el comando que ejecuta el agente invitado cuando agrega un usuario a un grupo. Linux Predeterminado
gpasswd_remove_cmd Establece el comando que ejecuta el agente invitado cuando se quita a un usuario de un grupo. Linux Predeterminado
groupadd_cmd Establece el comando que ejecuta el agente invitado cuando se crea un grupo nuevo. Linux Predeterminado

Núcleo

Usa las opciones de la sección Core del archivo instance_configs.cfg para controlar las funcionalidades principales del agente invitado.

Opción Descripción Sistema operativo Valor predeterminado
acs_client Si se configura como false, se inhabilita la comunicación del agente invitado con el plano de control del agente. Esto inhabilita funciones como las extensiones dinámicas de VM y la telemetría de agentes. Linux y Windows true
cloud_logging_enabled Si se establece en false, el agente invitado no envía registros de actividad a Cloud Logging. Linux y Windows true
log_file Si configuras esta opción, el agente invitado registrará los datos en un archivo local. Linux y Windows
log_level Establece el nivel de registro para los registros del agente invitado. Este parámetro de configuración se aplica a todos los registros que genera el agente invitado, no solo a Cloud Logging. Los ajustes y niveles son los siguientes:
  • 0 (FATAL): Registra los errores críticos que hacen que el agente se detenga.
  • 1 (ERROR): Registra los errores que podrían impedir que se ejecute el agente.
  • 2 (WARN): Registra condiciones potencialmente dañinas.
  • 3 (INFO): Registra mensajes informativos sobre la actividad del agente. Esta es la configuración predeterminada.
  • 4 (DEBUG): Registra información de depuración. Esta información puede ser detallada, pero puedes reducir el nivel de detalle con la opción log_verbosity.
 Linux y Windows 3
log_verbosity Establece el nivel de verbosidad del registro para los registros de DEBUG. Los valores aceptables van de 0 a 4. Cuanto más alto sea el valor, más detallada será la respuesta. Linux y Windows 0
enable_local_plugins Si se establece en true, el agente invitado instala e inicia de forma dinámica los complementos locales almacenados en el directorio de complementos locales configurado. Disponible para el agente de invitado 20260228.00 y versiones posteriores. Linux y Windows true

Daemons

Usa las opciones de la sección Daemons del archivo instance_configs.cfg para habilitar o inhabilitar daemons específicos en segundo plano que administra el agente invitado.

Opción Descripción Sistema operativo Valor predeterminado
accounts_daemon Si se configura como false, el agente invitado inhabilita la administración de cuentas de usuario y claves SSH. Linux true
clock_skew_daemon Si se configura como false, el agente invitado inhabilita la sincronización de relojes. Linux true
network_daemon Si se configura como false, el agente invitado inhabilita la administración de redes. Linux true

Configuración de las instancias

Usa las opciones de la sección InstanceSetup del archivo instance_configs.cfg para controlar varias tareas que realiza el agente invitado durante la configuración inicial de la instancia.

Opción Descripción Sistema operativo Valor predeterminado
host_key_types Es una lista separada por comas de los tipos de claves de host que se generarán. Linux ecdsa,ed25519,rsa
optimize_local_ssd Si se configura como false, el invitado no optimiza la SSD local durante el inicio. Linux true
network_enabled Si se configura como false, el agente invitado omite las funciones de configuración de la instancia que requieren información de metadatos. Si configuras esta opción como falsa, también se inhabilita la generación de claves de host y se evita que el agente invitado configure el archivo de configuración boto. Linux y Windows true
set_boto_config Si se establece en false, el agente invitado no crea ni actualiza el archivo de configuración boto. Es posible que las aplicaciones que usan la biblioteca de Boto y dependen de la configuración predeterminada del agente invitado para el acceso a Cloud Storage no funcionen como se espera sin la configuración manual de boto. Linux y Windows true
set_host_keys Si se configura como false, el agente invitado omite la generación de claves de host en el primer inicio. Linux true
set_multiqueue Si se establece en false, el agente invitado no intenta optimizar el rendimiento de la red habilitando las funciones de varias colas para los controladores de red. Cuando es true, el agente configura el sistema para que use varias filas para el tráfico de red, lo que podría mejorar la capacidad de procesamiento y reducir la latencia. Linux true

Reenvío de IP

Usa las opciones de la sección IpForwarding del archivo instance_configs.cfg para configurar cómo el agente invitado administra el reenvío y el enrutamiento de IP.

Opción Descripción Sistema operativo Valor predeterminado
ethernet_proto_id Es la cadena de ID del protocolo para las rutas agregadas por el daemon. Linux 66
ip_aliases Si se configura como false, el agente invitado no configura rutas de IP de alias. Linux true
target_instance_ips Si se configura como false, el agente invitado no habilita el balanceo de cargas de direcciones IP internas. Linux true

Workload Identity administrada

Usa las opciones de la sección MWLID del archivo instance_configs.cfg para configurar el bootstrapping de las credenciales de Workload Identity.

Opción Descripción Sistema operativo Valor predeterminado
enabled Si configuras enabled=true, el agente invitado inicia las credenciales de Workload Identity en las siguientes rutas de acceso de la VM:
  • Linux: /run/secrets/workload-spiffe-credentials
  • Windows: C:\ProgramData\Google\ComputeEngine\secrets\workload-spiffe-credentials
 Linux y Windows false
credential_refresh_minutes La frecuencia, en minutos, con la que se actualizan las credenciales de Workload Identity. Linux y Windows 10 minutos

Ejecución de secuencias de comandos de metadatos

Usa las opciones de la sección MetadataScripts del archivo instance_configs.cfg para controlar la ejecución de secuencias de comandos de metadatos, como las de inicio y cierre.

Opción Descripción Sistema operativo Valor predeterminado
default_shell Es el shell predeterminado para ejecutar secuencias de comandos. Linux /bin/bash
run_dir Es el directorio base para la ejecución de la secuencia de comandos de metadatos. Linux y Windows El valor predeterminado es el directorio temporal del sistema operativo. Por ejemplo, /tmp en Linux. Para identificar el directorio temporal, puedes usar la función os.TempDir().
startup Si se configura como false, el agente invitado no ejecuta secuencias de comandos de inicio desde los metadatos. Linux y Windows true
shutdown Si se configura como false, el agente invitado no ejecuta secuencias de comandos de cierre desde los metadatos. Linux y Windows true

Interfaces de red

Usa las opciones de la sección NetworkInterfaces del archivo instance_configs.cfg para controlar cómo el agente invitado administra las interfaces de red en la VM.

Opción Descripción Sistema operativo Valor predeterminado
setup Si se establece en false, el agente invitado omite la configuración de la interfaz de red. Linux true
ip_forwarding Si se configura como false, el agente invitado omite el reenvío de IP. Linux true
manage_primary_nic Si se configura como true, el agente invitado administra las NIC principales y secundarias. Linux false
dhcp_command Es la ruta de acceso a un ejecutable de DHCP alternativo para habilitar interfaces de red. Linux Vacío
restore_debian12_netplan_config Si se establece en true, el agente invitado vuelve a crear la configuración predeterminada de netplan de Debian 12 que se encuentra en /etc/netplan/90-default.yaml. Linux (Debian 12) true
vlan_setup_enabled Si se configura como true, el agente invitado configura y administra las NIC dinámicas. Linux false

Acceso al SO

Usa las opciones de la sección OSLogin del archivo instance_configs.cfg para configurar la integración del agente invitado con el Acceso al SO.

Opción Descripción Sistema operativo Valor predeterminado
cert_authentication Si se establece en false, el agente invitado no configura las claves TrustedUserCAKeys, AuthorizedPrincipalsCommand y AuthorizedPrincipalsCommandUser de sshd. Linux true

Administrador de complementos

Usa las opciones de la sección PluginConfig del archivo instance_configs.cfg para configurar el administrador de complementos del agente invitado.

Opción Descripción Sistema operativo Valor predeterminado
socket_connections_dir Es el directorio en el que el administrador de complementos crea sockets para comunicarse con los complementos. Linux y Windows
  • Linux: /run/google-guest-agent/plugin-connections
  • Windows: C:\ProgramData\Google\Compute Engine\google-guest-agent
state_dir Es el directorio en el que el administrador de complementos guarda el estado del complemento y descarga sus archivos binarios. Linux y Windows
  • Linux: /var/lib/google-guest-agent
  • Windows: C:\ProgramData\Google\Compute Engine\google-guest-agent
local_plugin_dir Es el directorio en el que el administrador de complementos busca complementos instalados de forma local. Disponible para las versiones 20260228.00 y posteriores. Linux y Windows
  • Linux: /usr/lib/google/guest_agent/
  • Windows: C:\Program Files\Google\Compute Engine\agent
connection_type Es el tipo de conexión que usa el agente invitado para comunicarse con sus extensiones. Solo se admiten los siguientes valores:
  • uds
  • tcp

Esta opción solo está disponible para las versiones 20260329.00 y posteriores del agente invitado.

 Linux y Windows uds

¿Qué sigue?