Configura l'agente ospite

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 file binari necessari alle istanze per essere eseguite su Compute Engine. Per saperne di più sull'ambiente guest, consulta Ambiente guest. L'agente guest funziona per impostazione predefinita con le impostazioni predefinite sulle immagini del sistema operativo fornite da Google, ma potresti voler personalizzarne il 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 sui sistemi operativi Linux e Windows. Su Linux, l'agente guest viene avviato come servizio systemd, mentre su Windows è un servizio di sistema.

I passaggi di 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 la versione 20250901.00 o successive dell'agente guest, 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 ospite: 

      Start-Service GCEAgent

    In alternativa, per riavviare l'agente ospite: 

    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 le funzionalità e impostare i 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:

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

    Ad esempio, per personalizzare la modalità di creazione di 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

    Nota:le distribuzioni Linux potrebbero fornire le proprie impostazioni predefinite in /etc/default/instance_configs.cfg.distro. L'agente legge prima queste impostazioni, ma quelle definite in /etc/default/instance_configs.cfg sovrascrivono i valori predefiniti di distribuzione. In questo modo, le tue configurazioni personalizzate non vengono perse durante gli aggiornamenti dei pacchetti.

  2. Dopo aver modificato il file di configurazione, riavvia l'agente guest affinché le modifiche diventino effettive.

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 seguenti tabelle 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 ospite.

Opzione Descrizione Sistema operativo Valore predefinito
deprovision_remove Se impostato su true, quando un account utente viene rimosso, viene eliminata anche la home directory dell'utente. Per impostazione predefinita, viene rimosso solo l'account utente e la directory rimane intatta. Linux false
groups Un elenco separato da virgole di gruppi per i nuovi utenti. Linux Vuoto
useradd_cmd Imposta il comando eseguito dall'agente ospite 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 Imposta il comando eseguito dall'agente guest quando viene eliminato un utente. Ad esempio, per rimuovere la home directory e i file dell'utente, imposta il valore su userdel -r. Linux Impostazione predefinita
usermod_cmd Imposta il comando eseguito dall'agente guest quando vengono modificati i gruppi di un utente. Linux Impostazione predefinita
gpasswd_add_cmd Imposta il comando eseguito dall'agente ospite quando aggiunge un utente a un gruppo. Linux Impostazione predefinita
gpasswd_remove_cmd Imposta il comando eseguito dall'agente ospite quando rimuove un utente da un gruppo. Linux Impostazione predefinita
groupadd_cmd Imposta il comando eseguito dall'agente ospite 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à principali dell'agente guest.

Opzione Descrizione Sistema operativo Valore predefinito
cloud_logging_enabled Se impostato su false, l'agente guest non invia i log delle attività a Cloud Logging. Linux e Windows true
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'interruzione dell'agente.
  • 1 (ERROR): registra gli errori che potrebbero impedire l'esecuzione dell'agente.
  • 2 (WARN): registra le 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 della registrazione nei log DEBUG. I valori accettabili vanno da 0 a 4. Più alto è il valore, più dettagliata è la risposta. Linux e Windows 0

Daemon

Utilizza le opzioni nella sezione Daemons del file instance_configs.cfg per attivare o disattivare 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 dell'account utente e della chiave SSH. Linux true
clock_skew_daemon Se impostato su false, l'agente ospite disattiva la sincronizzazione dell'orologio. Linux true
network_daemon Se impostato su false, l'agente ospite disattiva 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 imposti questa opzione su false, disattivi anche la generazione della chiave host e impedisci all'agente guest di 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 salta 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 attivando le funzionalità multiqueue per i driver di rete. Quando true, l'agente configura il sistema in modo da 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 la modalità di gestione dell'inoltro e del routing IP da parte dell'agente guest.

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 abilita il bilanciamento del carico dell'indirizzo IP interno. Linux true

Esecuzione dello script dei metadati

Utilizza le opzioni nella sezione MetadataScripts del file instance_configs.cfg per controllare l'esecuzione degli script di 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 /var/run/google-startup-scripts
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 guest 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

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

Passaggi successivi