Configurer l'agent invité

Ce document explique comment gérer le service d'agent invité et configurer ses fonctionnalités en modifiant son fichier de configuration.

L'agent invité est un composant essentiel de l'environnement invité. L'environnement invité contient des scripts, des daemons et des binaires dont les instances ont besoin pour s'exécuter sur Compute Engine. Pour en savoir plus sur l'environnement invité, consultez Environnement invité. Bien que l'agent invité fonctionne par défaut avec les paramètres par défaut sur les images d'OS fournies par Google, vous pouvez personnaliser son comportement. Pour en savoir plus sur les fonctions principales de l'agent invité, consultez Fonctionnalités de l'agent invité.

Redémarrer l'agent invité

L'agent invité s'exécute en tant que daemon sur les systèmes d'exploitation Linux et Windows. Sur Linux, l'agent invité se lance en tant que service systemd, et sur Windows, il s'agit d'un service système.

Les étapes de redémarrage varient selon le système d'exploitation (Linux ou Windows) :

Linux

Pour redémarrer sur Linux, choisissez l'une des options suivantes :

  • Pour la version 20250901.00 ou ultérieure de l'agent invité, exécutez la commande suivante :

    ggactl_plugin coreplugin restart

  • Pour les versions précédentes de l'agent invité, exécutez la commande suivante :

    systemctl restart google-guest-agent

Windows

Pour redémarrer sur Windows, choisissez l'une des options suivantes :

  • Pour la version 20250901.00 ou ultérieure de l'agent invité, exécutez la commande suivante :

    ggactl_plugin coreplugin restart

  • Pour les versions précédentes de l'agent invité, utilisez les commandes PowerShell suivantes :

    1. Pour arrêter l'agent invité : 

      Stop-Service GCEAgent

    2. Pour démarrer l'agent invité : 

      Start-Service GCEAgent

    Vous pouvez également redémarrer l'agent invité : 

    Restart-Service GCEAgent

Pour toutes les versions de l'agent invité, vous pouvez également utiliser le Gestionnaire des tâches : recherchez le service GCEGuestAgent, puis redémarrez-le.

Mettre à jour le fichier de configuration de l'agent invité

Vous pouvez personnaliser le comportement de l'agent invité en modifiant son fichier de configuration, instance_configs.cfg. Ce fichier vous permet d'activer ou de désactiver des fonctionnalités, et de définir des valeurs par défaut pour les opérations.

Pour modifier le fichier instance_configs.cfg sur les systèmes d'exploitation Linux et Windows, consultez les sections suivantes.

Linux

Pour modifier le fichier de configuration sur une VM Linux, procédez comme suit :

  1. Créez ou modifiez le fichier de configuration situé à l'adresse /etc/default/instance_configs.cfg et définissez l'option requise. Pour obtenir la liste des options, consultez Options de configuration.

    Par exemple, pour personnaliser la façon dont les nouveaux utilisateurs sont créés et spécifier les types de clés hôtes SSH à générer, créez ou mettez à jour le fichier avec le contenu suivant :

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

    Remarque : Les distributions Linux peuvent fournir leurs propres paramètres par défaut dans /etc/default/instance_configs.cfg.distro. L'agent lit d'abord ces paramètres, mais tous les paramètres que vous définissez dans /etc/default/instance_configs.cfg remplacent les paramètres de distribution par défaut. Cela garantit que vos configurations personnalisées ne sont pas perdues lors des mises à jour de packages.

  2. Après avoir modifié le fichier de configuration, redémarrez l'agent invité pour que les modifications prennent effet.

Windows

Sur les VM Windows, le fichier de configuration se trouve à l'emplacement C:\Program Files\Google\Compute Engine\instance_configs.cfg. Pour en savoir plus sur la configuration de l'agent sur Windows, consultez Activer et désactiver les fonctionnalités d'instance Windows.

Options de configuration

Les tableaux suivants listent les options de configuration disponibles pour le fichier instance_configs.cfg.

Comptes

Utilisez les options de la section Accounts du fichier instance_configs.cfg pour contrôler la gestion des utilisateurs et des groupes par l'agent invité.

Option Description Système d'exploitation Valeur par défaut
deprovision_remove Si la valeur est définie sur true, le répertoire personnel de l'utilisateur est également supprimé lorsque son compte est supprimé. Par défaut, seul le compte utilisateur est supprimé, et l'annuaire reste intact. Linux false
groups Liste de groupes séparés par une virgule pour les nouveaux utilisateurs. Linux Vide
useradd_cmd Définit la commande que l'agent invité exécute lors de la création d'un utilisateur. Par exemple, pour créer le répertoire personnel d'un utilisateur et l'ajouter au groupe google-sudoers, définissez la valeur sur useradd -m -G google-sudoers. Linux Valeur système par défaut
userdel_cmd Définit la commande que l'agent invité exécute lorsqu'un utilisateur est supprimé. Par exemple, pour supprimer le répertoire personnel et les fichiers de l'utilisateur, définissez la valeur sur userdel -r. Linux Valeur système par défaut
usermod_cmd Définit la commande que l'agent invité exécute lors de la modification des groupes d'un utilisateur. Linux Valeur système par défaut
gpasswd_add_cmd Définit la commande que l'agent invité exécute lorsqu'un utilisateur est ajouté à un groupe. Linux Valeur système par défaut
gpasswd_remove_cmd Définit la commande que l'agent invité exécute lorsqu'il supprime un utilisateur d'un groupe. Linux Valeur système par défaut
groupadd_cmd Définit la commande que l'agent invité exécute lors de la création d'un groupe. Linux Valeur système par défaut

Core

Utilisez les options de la section Core du fichier instance_configs.cfg pour contrôler les fonctionnalités de base de l'agent invité.

Option Description Système d'exploitation Valeur par défaut
cloud_logging_enabled Si la valeur est définie sur false, l'agent invité n'envoie pas les journaux d'activité à Cloud Logging. Linux et Windows true
log_level Définit le niveau de journalisation des journaux de l'agent invité. Ce paramètre s'applique à tous les journaux générés par l'agent invité, et pas seulement à Cloud Logging. Voici les paramètres et les niveaux :
  • 0 (FATAL) : enregistre les erreurs critiques qui entraînent l'arrêt de l'agent.
  • 1 (ERROR) : enregistre les erreurs qui pourraient empêcher l'agent de s'exécuter.
  • 2 (WARN) : enregistre les conditions potentiellement dangereuses.
  • 3 (INFO) : enregistre les messages d'information sur l'activité de l'agent. Il s'agit du paramètre par défaut.
  • 4 (DEBUG) : enregistre les informations de débogage. Ces informations peuvent être très détaillées, mais vous pouvez réduire le niveau de détail à l'aide de l'option log_verbosity.
 Linux et Windows 3
log_verbosity Définit le niveau de verbosité de la journalisation pour les journaux DEBUG. Les valeurs acceptées vont de 0 à 4. Plus la valeur est élevée, plus la réponse est détaillée. Linux et Windows 0

Daemons

Utilisez les options de la section Daemons du fichier instance_configs.cfg pour activer ou désactiver des daemons d'arrière-plan spécifiques gérés par l'agent invité.

Option Description Système d'exploitation Valeur par défaut
accounts_daemon Si la valeur est définie sur false, l'agent invité désactive la gestion des comptes utilisateur et des clés SSH. Linux true
clock_skew_daemon Si la valeur est définie sur false, l'agent invité désactive la synchronisation de l'horloge. Linux true
network_daemon S'il est défini sur false, l'agent invité désactive la gestion du réseau. Linux true

Configurer l'instance

Utilisez les options de la section InstanceSetup du fichier instance_configs.cfg pour contrôler diverses tâches effectuées par l'agent invité lors de la configuration initiale de l'instance.

Option Description Système d'exploitation Valeur par défaut
host_key_types Liste de types de clés d'hôte à générer, séparés par une virgule. Linux ecdsa,ed25519,rsa
optimize_local_ssd Si la valeur est définie sur false, l'invité n'optimise pas le SSD local au démarrage. Linux true
network_enabled Si la valeur est définie sur false, l'agent invité ignore les fonctions de configuration de l'instance qui nécessitent des informations de métadonnées. Si vous définissez cette option sur "false", la génération de clés hôtes est également désactivée et l'agent invité ne peut pas configurer le fichier de configuration boto. Linux et Windows true
set_boto_config Si la valeur est définie sur false, l'agent invité ne crée ni ne met à jour le fichier de configuration boto. Les applications qui utilisent la bibliothèque Boto et s'appuient sur la configuration par défaut de l'agent invité pour l'accès à Cloud Storage peuvent ne pas fonctionner comme prévu sans configuration manuelle de boto. Linux et Windows true
set_host_keys Si la valeur définie est false, l'agent invité ne génère pas de clés d'hôte lors du premier démarrage. Linux true
set_multiqueue Si la valeur est définie sur false, l'agent invité ne tente pas d'optimiser les performances du réseau en activant les fonctionnalités multiqueues pour les pilotes réseau. Lorsque la valeur est true, l'agent configure le système pour qu'il utilise plusieurs files d'attente pour le trafic réseau, ce qui peut améliorer le débit et réduire la latence. Linux true

Transfert IP

Utilisez les options de la section IpForwarding du fichier instance_configs.cfg pour configurer la façon dont l'agent invité gère le transfert et le routage d'adresses IP.

Option Description Système d'exploitation Valeur par défaut
ethernet_proto_id Chaîne d'ID de protocole pour les routes ajoutées par le démon. Linux 66
ip_aliases Si la valeur est false, l'agent invité ne configure pas les routes d'adresses IP d'alias. Linux true
target_instance_ips Si la valeur est définie sur false, l'agent invité n'active pas l'équilibrage de charge des adresses IP internes. Linux true

Exécution de scripts de métadonnées

Utilisez les options de la section MetadataScripts du fichier instance_configs.cfg pour contrôler l'exécution des scripts de métadonnées, tels que les scripts de démarrage et d'arrêt.

Option Description Système d'exploitation Valeur par défaut
default_shell Shell par défaut pour exécuter les scripts. Linux /bin/bash
run_dir Répertoire de base pour l'exécution du script de métadonnées. Linux /var/run/google-startup-scripts
startup Si la valeur est définie sur false, l'agent invité n'exécute pas les scripts de démarrage à partir des métadonnées. Linux et Windows true
shutdown Si la valeur est définie sur false, l'agent invité n'exécute pas les scripts d'arrêt à partir des métadonnées. Linux et Windows true

Interfaces réseau

Utilisez les options de la section NetworkInterfaces du fichier instance_configs.cfg pour contrôler la façon dont l'agent invité gère les interfaces réseau sur la VM.

Option Description Système d'exploitation Valeur par défaut
setup Si la valeur est définie sur false, l'agent invité ignore la configuration de l'interface réseau. Linux true
ip_forwarding Si la valeur est définie sur false, l'agent invité ignore le transfert IP. Linux true
manage_primary_nic Si la valeur est définie sur true, l'agent invité gère les cartes d'interface réseau principale et secondaire. Linux false
dhcp_command Chemin d'accès à un exécutable DHCP alternatif pour activer les interfaces réseau. Linux Vide
restore_debian12_netplan_config Si la valeur est définie sur true, l'agent invité recrée la configuration netplan par défaut de Debian 12, qui se trouve à l'emplacement /etc/netplan/90-default.yaml. Linux (Debian 12) true

OS Login

Utilisez les options de la section OSLogin du fichier instance_configs.cfg pour configurer l'intégration de l'agent invité à OS Login.

Option Description Système d'exploitation Valeur par défaut
cert_authentication Si la valeur est définie sur false, l'agent invité ne configure pas les clés TrustedUserCAKeys, AuthorizedPrincipalsCommand et AuthorizedPrincipalsCommandUser de sshd. Linux true

Étapes suivantes