Configura l'agente ospite

Linux Windows

Questo documento descrive come gestire il servizio dell'agente guest e configurarne le funzionalità modificando il file di configurazione.

L'agente guest è un componente fondamentale dell'ambiente guest. L'ambiente guest contiene script, daemon e programmi binari necessari per l'esecuzione delle istanze su Compute Engine. Per saperne di più sull'ambiente guest, consulta Ambiente guest. Sebbene l'agente guest funzioni per impostazione predefinita con le impostazioni predefinite sulle immagini sistema operativo fornite da Google, potresti voler personalizzare il suo comportamento. Per saperne di più sulle funzioni principali dell'agente guest, consulta Funzionalità dell'agente guest.

Riavvia l'agente guest

L'agente guest viene eseguito come daemon sia sui sistemi operativi Linux che Windows. Su Linux, l'agente guest viene avviato come servizio systemd, mentre su Windows è un servizio di sistema.

I passaggi per il riavvio variano tra i sistemi operativi Linux e Windows come segue:

Linux

Per riavviare su Linux, scegli una delle seguenti opzioni:

• Per la versione 20250901.00 o successive dell'agente guest, esegui questo comando:

  ggactl_plugin coreplugin restart

• Per le versioni precedenti dell'agente guest, esegui questo comando:

  systemctl restart google-guest-agent

Windows

Per riavviare su Windows, scegli una delle seguenti opzioni:

• Per l'agente guest versione 20250901.00 o successive, esegui questo comando:

  ggactl_plugin coreplugin restart

• Per le versioni precedenti dell'agente guest, utilizza i seguenti comandi PowerShell:

  1. Per arrestare l'agente ospite:

     Stop-Service GCEAgent

  2. Per avviare l'agente guest:

     Start-Service GCEAgent

  In alternativa, per riavviare l'agente guest:

  Restart-Service GCEAgent

Per tutte le versioni dell'agente ospite, puoi anche utilizzare Task Manager: trova il servizio GCEGuestAgent e riavvialo.

Aggiorna il file di configurazione dell'agente guest

Puoi personalizzare il comportamento dell'agente ospite modificando il file di configurazione, instance_configs.cfg. Questo file ti consente di attivare o disattivare funzionalità e impostare valori predefiniti per le operazioni.

Per modificare il file instance_configs.cfg sui sistemi operativi Linux e Windows, esamina le seguenti sezioni.

Linux

Per modificare il file di configurazione su una VM Linux, segui questi passaggi:

1. Crea o modifica il file di configurazione in /etc/default/instance_configs.cfg e imposta l'opzione richiesta. Per un elenco delle opzioni, consulta Opzioni di configurazione.

   Ad esempio, per personalizzare la modalità di creazione dei nuovi utenti e specificare i tipi di chiavi host SSH da generare, crea o aggiorna il file con i seguenti contenuti:

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

2. Dopo aver modificato il file di configurazione, riavvia l'agente guest per applicare le modifiche.

Precedenza dei file di configurazione

L'agente guest legge le impostazioni di configurazione da /etc/default/instance_configs.cfg e dalle relative varianti .distro e .template. Questi file vengono elaborati in una gerarchia specifica per consentire agli utenti e alle distribuzioni Linux di impostare i valori predefiniti. L'ordine di precedenza, dal più alto al più basso, è il seguente:

1. /etc/default/instance_configs.cfg.template (priorità più elevata)
2. /etc/default/instance_configs.cfg.distro
3. /etc/default/instance_configs.cfg (priorità più bassa)

Ad esempio, puoi definire i valori predefiniti nel file .template che ignorano le impostazioni di base sia della distribuzione Linux sia del pacchetto dell'agente guest.

Windows

Sulle VM Windows, il file di configurazione si trova in C:\Program Files\Google\Compute Engine\instance_configs.cfg. Per informazioni dettagliate sulla configurazione dell'agente su Windows, vedi Attivazione e disattivazione delle funzionalità delle istanze Windows.

Opzioni di configurazione

Le tabelle seguenti elencano le opzioni di configurazione disponibili per il file instance_configs.cfg.

Account

Utilizza le opzioni nella sezione Accounts del file instance_configs.cfg per controllare la gestione di utenti e gruppi da parte dell'agente guest.

Opzione	Descrizione	Sistema operativo	Valore predefinito
deprovision_remove	Se impostato su true, l'agente guest rimuove l'account utente quando esegui il deprovisioning di un utente. Per impostazione predefinita (se impostato su false), l'agente ospite rimuove l'utente solo dal gruppo google-sudoers ed elimina le sue chiavi SSH, ma non rimuove l'account utente.	Linux	false
groups	Un elenco separato da virgole di gruppi per i nuovi utenti.	Linux	adm,dip,docker,lxd,plugdev,video
useradd_cmd	Imposta il comando eseguito dall'agente guest durante la creazione di un nuovo utente. Ad esempio, per creare la home directory di un utente e aggiungerlo al gruppo google-sudoers, imposta il valore su useradd -m -G google-sudoers.	Linux	Impostazione predefinita
userdel_cmd	Specifica il comando eseguito dall'agente guest per eliminare un utente quando deprovision_remove è true. Ad esempio, imposta questa opzione su userdel -r per rimuovere la home directory e i file dell'utente.	Linux	Impostazione predefinita
usermod_cmd	Imposta il comando eseguito dall'agente guest durante la modifica dei gruppi di un utente.	Linux	Impostazione predefinita
gpasswd_add_cmd	Imposta il comando eseguito dall'agente guest quando aggiunge un utente a un gruppo.	Linux	Impostazione predefinita
gpasswd_remove_cmd	Imposta il comando eseguito dall'agente guest quando rimuove un utente da un gruppo.	Linux	Impostazione predefinita
groupadd_cmd	Imposta il comando eseguito dall'agente guest durante la creazione di un nuovo gruppo.	Linux	Impostazione predefinita

Definizione

Utilizza le opzioni nella sezione Core del file instance_configs.cfg per controllare le funzionalità di base dell'agente guest.

Opzione	Descrizione	Sistema operativo	Valore predefinito
acs_client	Se impostato su false, la comunicazione dell'agente guest con il control plane dell'agente è disabilitata. In questo modo vengono disattivate funzionalità come le estensioni VM dinamiche e la telemetria dell'agente.	Linux e Windows	true
cloud_logging_enabled	Se impostato su false, l'agente guest non invia i log delle attività a Cloud Logging.	Linux e Windows	true
log_file	Se imposti questa opzione, i log dell'agente ospite vengono registrati in un file locale.	Linux e Windows
log_level	Imposta il livello di logging per i log dell'agente guest. Questa impostazione si applica a tutti i log generati dall'agente guest, non solo a Cloud Logging. Le impostazioni e i livelli sono i seguenti: 0 (FATAL): registra gli errori critici che causano l'arresto dell'agente. 1 (ERROR): registra gli errori che potrebbero impedire l'esecuzione dell'agente. 2 (WARN): registra condizioni potenzialmente dannose. 3 (INFO): registra i messaggi informativi sull'attività dell'agente. Questa è l'impostazione predefinita. 4 (DEBUG): registra le informazioni di debug. Queste informazioni possono essere dettagliate, ma puoi ridurre il livello di dettaglio utilizzando l'opzione log_verbosity.	Linux e Windows	3
log_verbosity	Imposta il livello di dettaglio del logging per i log di DEBUG. I valori accettabili sono compresi tra 0 e 4. Più alto è il valore, più dettagliata è la risposta.	Linux e Windows	0
enable_local_plugins	Se impostato su true, l'agente ospite installa e avvia dinamicamente i plug-in locali archiviati nella directory dei plug-in locali configurata. Disponibile per l'agente ospite 20260228.00 e versioni successive.	Linux e Windows	true

Daemon

Utilizza le opzioni nella sezione Daemons del file instance_configs.cfg per abilitare o disabilitare daemon di sfondo specifici gestiti dall'agente guest.

Opzione	Descrizione	Sistema operativo	Valore predefinito
accounts_daemon	Se impostato su false, l'agente guest disattiva la gestione delle chiavi SSH e degli account utente.	Linux	true
clock_skew_daemon	Se impostato su false, l'agente guest disattiva la sincronizzazione dell'orologio.	Linux	true
network_daemon	Se impostato su false, l'agente guest disabilita la gestione della rete.	Linux	true

Configurazione dell'istanza

Utilizza le opzioni nella sezione InstanceSetup del file instance_configs.cfg per controllare varie attività eseguite dall'agente guest durante la configurazione iniziale dell'istanza.

Opzione	Descrizione	Sistema operativo	Valore predefinito
host_key_types	Un elenco separato da virgole dei tipi di chiavi host da generare.	Linux	ecdsa,ed25519,rsa
optimize_local_ssd	Se impostato su false, il guest non ottimizza l'SSD locale all'avvio.	Linux	true
network_enabled	Se impostato su false, l'agente guest ignora le funzioni di configurazione dell'istanza che richiedono informazioni sui metadati. Se questa opzione viene impostata su false, viene disattivata anche la generazione della chiave host e l'agente guest non può configurare il file di configurazione boto.	Linux e Windows	true
set_boto_config	Se impostato su false, l'agente guest non crea né aggiorna il file di configurazione boto. Le applicazioni che utilizzano la libreria Boto e si basano sulla configurazione predefinita dell'agente guest per l'accesso a Cloud Storage potrebbero non funzionare come previsto senza la configurazione manuale di boto.	Linux e Windows	true
set_host_keys	Se impostato su false, l'agente guest ignora la generazione delle chiavi host al primo avvio.	Linux	true
set_multiqueue	Se impostato su false, l'agente guest non tenta di ottimizzare le prestazioni di rete abilitando le funzionalità multiqueue per i driver di rete. Se impostato su true, l'agente configura il sistema per utilizzare più code per il traffico di rete, migliorando potenzialmente il throughput e riducendo la latenza.	Linux	true

Inoltro IP

Utilizza le opzioni nella sezione IpForwarding del file instance_configs.cfg per configurare il modo in cui l'agente guest gestisce l'inoltro e il routing IP.

Opzione	Descrizione	Sistema operativo	Valore predefinito
ethernet_proto_id	La stringa ID protocollo per le route aggiunte dal daemon.	Linux	66
ip_aliases	Se impostato su false, l'agente guest non configura le route IP alias.	Linux	true
target_instance_ips	Se impostato su false, l'agente guest non attiva il bilanciamento del carico degli indirizzi IP interni.	Linux	true

Workload Identity gestita

Utilizza le opzioni nella sezione MWLID del file instance_configs.cfg per configurare il bootstrap delle credenziali di Workload Identity.

Opzione	Descrizione	Sistema operativo	Valore predefinito
enabled	Se imposti enabled=true, l'agente guest esegue il bootstrap delle credenziali di Workload Identity nei seguenti percorsi sulla VM: Linux: /run/secrets/workload-spiffe-credentials Windows: C:\ProgramData\Google\ComputeEngine\secrets\workload-spiffe-credentials	Linux e Windows	false
credential_refresh_minutes	La frequenza, in minuti, con cui vengono aggiornate le credenziali di Workload Identity.	Linux e Windows	10 minuti

Esecuzione di script di metadati

Utilizza le opzioni nella sezione MetadataScripts del file instance_configs.cfg per controllare l'esecuzione degli script dei metadati, ad esempio gli script di avvio e arresto.

Opzione	Descrizione	Sistema operativo	Valore predefinito
default_shell	La shell predefinita per l'esecuzione degli script.	Linux	/bin/bash
run_dir	La directory di base per l'esecuzione dello script dei metadati.	Linux e Windows	Il valore predefinito è la directory temporanea del sistema operativo. Ad esempio, /tmp su Linux. Per identificare la directory temporanea, puoi utilizzare la funzione os.TempDir().
startup	Se impostato su false, l'agente guest non esegue gli script di avvio dai metadati.	Linux e Windows	true
shutdown	Se impostato su false, l'agente guest non esegue gli script di arresto dai metadati.	Linux e Windows	true

Interfacce di rete

Utilizza le opzioni nella sezione NetworkInterfaces del file instance_configs.cfg per controllare il modo in cui l'agente guest gestisce le interfacce di rete sulla VM.

Opzione	Descrizione	Sistema operativo	Valore predefinito
setup	Se impostato su false, l'agente guest salta la configurazione dell'interfaccia di rete.	Linux	true
ip_forwarding	Se impostato su false, l'agente ospite salta l'inoltro IP.	Linux	true
manage_primary_nic	Se impostato su true, l'agente guest gestisce le NIC principali e secondarie.	Linux	false
dhcp_command	Il percorso di un eseguibile DHCP alternativo per l'attivazione delle interfacce di rete.	Linux	Vuoto
restore_debian12_netplan_config	Se impostato su true, l'agente guest ricrea la configurazione netplan predefinita di Debian 12 che si trova in /etc/netplan/90-default.yaml.	Linux (Debian 12)	true
vlan_setup_enabled	Se impostato su true, l'agente guest configura e gestisce le NIC dinamiche.	Linux	false

OS Login

Utilizza le opzioni nella sezione OSLogin del file instance_configs.cfg per configurare l'integrazione dell'agente guest con OS Login.

Opzione	Descrizione	Sistema operativo	Valore predefinito
cert_authentication	Se impostato su false, l'agente guest non configura le chiavi TrustedUserCAKeys, AuthorizedPrincipalsCommand e AuthorizedPrincipalsCommandUser di sshd.	Linux	true

Gestione plug-in

Utilizza le opzioni della sezione PluginConfig del file instance_configs.cfg per configurare il gestore dei plug-in dell'agente guest.

Opzione	Descrizione	Sistema operativo	Valore predefinito
socket_connections_dir	La directory in cui il gestore dei plug-in crea i socket per comunicare con i plug-in.	Linux e Windows	Linux: /run/google-guest-agent/plugin-connections Windows: C:\ProgramData\Google\Compute Engine\google-guest-agent
state_dir	La directory in cui il gestore dei plug-in salva lo stato dei plug-in e scarica i relativi file binari.	Linux e Windows	Linux: /var/lib/google-guest-agent Windows: C:\ProgramData\Google\Compute Engine\google-guest-agent
local_plugin_dir	La directory in cui il gestore dei plug-in cerca i plug-in installati localmente. Disponibile per le versioni 20260228.00 e successive.	Linux e Windows	Linux: /usr/lib/google/guest_agent/ Windows: C:\Program Files\Google\Compute Engine\agent
connection_type	Il tipo di connessione utilizzato dall'agente ospite per comunicare con le sue estensioni. Sono supportati solo i seguenti valori: uds tcp Questa opzione è disponibile solo per le versioni dell'agente guest 20260329.00 e successive.	Linux e Windows	uds

Passaggi successivi

• Visualizza l'output della porta seriale per controllare i log dell'agente guest e risolvere i problemi.