Résoudre les problèmes liés aux extensions de VM

Ce document explique comment vérifier l'installation d'une extension de VM, diagnostiquer les problèmes de déploiement de règles et d'état d'extension de VM, et afficher les journaux de débogage de l'agent invité sur les instances de machines virtuelles (VM) Compute Engine. Suivez ces instructions pour identifier pourquoi une extension attendue ne s'est pas installée, pourquoi une extension inattendue s'exécute sur une VM ou pourquoi un processus d'extension s'est arrêté.

Avant de commencer

Avant de résoudre les problèmes d'extension de VM sur vos VM, remplissez les conditions préalables suivantes :

  • Vérifiez que vous disposez des autorisations requises pour inspecter les règles d'extension, les métadonnées des extensions compatibles avec VM Extension Manager et les états des extensions de VM dans votre hiérarchie de ressources Google Cloud . Pour en savoir plus, consultez Afficher les détails et l'état des extensions de VM.
  • Pour identifier les échecs d'installation, les plantages ou les rollbacks avant de vous connecter à des VM individuelles, consultez l'historique des événements d'application des extensions dans Cloud Logging. Pour en savoir plus, consultez Afficher les journaux d'extension de VM.
  • Pour inspecter les processus d'extension en cours d'exécution et les journaux de débogage de l'agent invité directement sur une VM, vérifiez que vous pouvez vous connecter à la VM à l'aide de SSH ou de RDP.

Vérifier qu'une extension est installée

Pour vérifier si une extension est installée et s'exécute sur une VM Compute Engine, inspectez l'état de l'extension de la VM à l'aide des méthodes en lecture seule. Ne vous connectez à la VM que si vous avez besoin d'informations sur les processus ou les journaux de l'OS invité.

Inspecter l'état de l'extension de VM à l'aide des méthodes en lecture seule

Pour vérifier l'état d'exécution et l'état de santé des extensions installées sans vous connecter à la VM, exécutez la commande gcloud beta compute instances list-vm-extension-states ou gcloud beta compute instances get-vm-extension-state, ou appelez les méthodes d'API REST équivalentes. La réponse renvoie la version active de chaque extension, l'état d'application (enforcementState), l'état de fonctionnement (healthStatus), le message de diagnostic (healthMsg) et l'ID de la règle applicable (policyId). Pour en savoir plus, consultez Afficher les états des extensions de VM sur une instance.

Inspecter les processus d'extension en cours d'exécution sur la VM

Si les requêtes d'état à distance ne renvoient pas l'état attendu, connectez-vous à la VM et vérifiez si le processus d'extension est en cours d'exécution dans le système d'exploitation invité.

Le tableau suivant liste les noms de processus pour chaque extension compatible :

Nom de l'extension Nom du processus d'extension
google-cloud-sap-extension google_cloud_sap_agent
google-cloud-workload-extension google_cloud_workload_agent
ops-agent ops_agent

Pour vérifier si le processus d'extension est en cours d'exécution sur votre VM, sélectionnez votre système d'exploitation :

Linux

Pour lister le processus d'extension en cours d'exécution, exécutez la commande suivante :

ps aux | grep 'EXTENSION_PROCESS_NAME'
 Remplacez EXTENSION_PROCESS_NAME par le nom du processus de l'extension indiqué dans le tableau précédent. Par exemple, pour lister le processus d'extension ops-agent, exécutez la commande suivante : 
ps aux | grep 'ops_agent'

Windows

Pour lister le processus d'extension en cours d'exécution, exécutez la commande suivante :

tasklist | findstr "EXTENSION_PROCESS_NAME"
 Remplacez EXTENSION_PROCESS_NAME par le nom du processus de l'extension indiqué dans le tableau précédent. Par exemple, pour lister le processus d'extension ops-agent, exécutez la commande suivante : 
tasklist | findstr "ops_agent"

L'extrait de code suivant montre un exemple de résultat de la commande ps lorsque l'extension ops-agent est exécutée sur une VM Linux :

....
/var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3
....

Examiner les entrées d'installation de l'agent invité

Pour confirmer que l'agent invité a téléchargé, extrait et démarré un plug-in d'extension, activez et affichez les journaux de débogage de l'agent invité.

L'extrait suivant montre des exemples d'entrées de journal de l'agent invité lorsque l'agent invité installe et démarre l'extension ops-agent sur une VM Linux :

my-instance google_guest_agent [14972]: Installing plugin "ops-agent", revision "2dfa648c1892da87"
my-instance google_guest_agent [14972]: (client.go:181) Sent message [[type.googleapis.com/agent_controlplane.PluginEventMessage: (revision_id:"2dfa648c1892da87)]]
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-central1-a/ops-agent
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "UnpackPluginArchiveStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:361) Successfully unpacked "/var/lib/google-guest-agent/ops-agent.tar.gz" to "/google-guest-agent/ops-agent_2dfa648c1892da87
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)
my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent 2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

Résoudre les problèmes d'installation

Si une extension n'est pas installée sur une VM ou si une extension inattendue s'exécute sur une VM, diagnostiquez le déploiement de la règle, les libellés cibles et l'état d'application avant de réessayer l'installation.

Pour identifier la raison pour laquelle l'installation d'une extension a échoué sur une VM, procédez comme suit :

  1. Attendez que les règles soient appliquées. Le déploiement d'une règle, y compris les nouvelles tentatives, peut prendre jusqu'à une heure sur les VM cibles. Pour en savoir plus sur l'inspection de la progression du déploiement, consultez Afficher les règles d'extension.
  2. Vérifiez que les étiquettes d'inclusion que vous avez spécifiées dans la règle correspondent aux étiquettes de la VM, puis vérifiez les métadonnées des extensions compatibles avec VM Extension Manager :
    • Pour vérifier les sélecteurs d'étiquettes de stratégie et les numéros de priorité dans votre organisation, votre dossier ou votre projet, consultez Afficher les règles d'extension.
    • Pour vérifier les noms, les numéros de version et les niveaux de compatibilité des extensions prises en charge par VM Extension Manager dans toutes les zones ou dans une zone spécifique, consultez Afficher les extensions et les versions de VM.
  3. Pour vérifier l'état d'application, l'état de santé, le message de diagnostic et l'ID de la règle applicable (policyId), inspectez l'état de l'extension sur la VM concernée. Les états d'erreur courants incluent INSTALL_FAILED, INCOMPATIBLE et ROLLED_BACK. Lorsque plusieurs règles ciblent la même VM, le champ policyId indique quelle règle régit chaque extension. Pour en savoir plus, consultez Afficher les états des extensions de VM sur une instance.
  4. Pour identifier les erreurs d'installation au niveau de l'invité sur la VM, activez et affichez les journaux de débogage de l'agent invité.

Réessayer d'installer l'extension

Après avoir résolu le problème de configuration de la règle ou de l'OS invité sous-jacent, réappliquez la configuration de la règle pour que l'agent invité tente à nouveau l'installation sur les VM concernées.

Pour réessayer d'installer l'extension, choisissez l'une des options suivantes :

  • Recréez la règle : supprimez la règle, puis créez-en une autre.

  • Appliquer une règle temporaire de priorité plus élevée : pour réessayer l'installation sur des VM spécifiques sans recréer de règle affectant un grand parc, procédez comme suit :

    1. Ajoutez un libellé temporaire, tel que status=failed, aux VM sur lesquelles l'installation a échoué.

    2. Créez une règle temporaire avec une priorité plus élevée (une valeur entière inférieure) qui cible le libellé temporaire. Par exemple, si la stratégie d'origine utilise la priorité par défaut 1000, exécutez la commande suivante pour créer une stratégie temporaire avec la priorité 500 :

      gcloud compute zone-vm-extension-policies create temp-policy \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --priority=500 \
    --inclusion-labels=status=failed

    3. Une fois que l'agent invité a installé l'extension sur les VM cibles, supprimez la règle temporaire.

    4. Supprimez l'étiquette temporaire des VM. L'extension reste installée, car la règle d'origine régit toujours ces VM.

Afficher les journaux de débogage de l'agent invité

Si les requêtes d'état à distance et les journaux d'événements Logging n'indiquent pas pourquoi une extension n'a pas pu être téléchargée ou démarrée, activez la journalisation de débogage détaillée dans la section Core du fichier de configuration de l'agent invité.

Pour activer et afficher les journaux de débogage de l'agent invité, sélectionnez votre système d'exploitation :

Linux

Pour activer la journalisation de débogage sur une VM Linux, procédez comme suit :

  1. Ouvrez le fichier de configuration de l'agent invité à l'emplacement /etc/default/instance_configs.cfg.

  2. Dans /etc/default/instance_configs.cfg, ajoutez les paramètres suivants. Si la section [Core] existe déjà, ajoutez log_level et log_verbosity sous [Core] :

    [Core]
log_level = 4
log_verbosity = 4

  3. Pour redémarrer le gestionnaire de l'agent invité, exécutez la commande suivante :

    sudo systemctl restart google-guest-agent-manager

  4. Pour afficher les journaux de l'agent invité générés lors de l'installation de l'extension, exécutez la commande suivante :

    journalctl -u google-guest-agent-manager

Windows

Pour activer la journalisation de débogage sur une VM Windows, procédez comme suit :

  1. Ouvrez le fichier de configuration de l'agent invité à l'emplacement C:\Program Files\Google\Compute Engine\instance_configs.cfg.

  2. Dans instance_configs.cfg, ajoutez les paramètres suivants. Si la section [Core] existe déjà, ajoutez log_level et log_verbosity sous [Core] :

    [Core]
log_level = 4
log_verbosity = 4

  3. Dans une invite de commande ou une fenêtre PowerShell avec des droits d'administrateur, exécutez les commandes suivantes pour redémarrer le gestionnaire de l'agent invité :

    net stop GCEAgentManager
net start GCEAgentManager

  4. Dans PowerShell, pour afficher les journaux de l'agent invité générés lors de l'installation de l'extension, exécutez la commande suivante :

    Get-Eventlog -Source google_guest_agent_manager -LogName Application

Résoudre les erreurs courantes dans les journaux de l'agent invité

Lorsque vous inspectez les journaux de débogage de l'agent invité, recherchez les erreurs de contrainte de ressources qui empêchent l'extraction ou l'exécution des extensions sur la VM.

Le tableau suivant liste les erreurs courantes signalées dans les journaux de débogage de l'agent invité et indique comment les résoudre :

Condition d'erreur Solution
Espace disque insuffisant Si les journaux indiquent que la VM ne dispose pas de suffisamment d'espace disque pour télécharger ou extraire l'archive de l'extension, supprimez les fichiers inutilisés ou redimensionnez le disque de démarrage.
Utilisation excessive des ressources Si les journaux indiquent que l'agent invité a arrêté l'extension en raison d'une utilisation élevée de la mémoire ou du processeur, remplacez le type de machine de la VM par un type de machine comportant davantage de mémoire ou de processeurs virtuels.

Étapes suivantes