Fehlerbehebung bei VM-Erweiterungen

In diesem Dokument wird beschrieben, wie Sie die Installation von VM-Erweiterungen überprüfen, Probleme beim Richtlinien-Rollout und beim Status von VM-Erweiterungen diagnostizieren und Debugging-Logs des Gast-Agents auf Compute Engine-VM-Instanzen aufrufen. Anhand dieser Anleitung können Sie herausfinden, warum eine erwartete Erweiterung nicht installiert wurde, warum eine unerwartete Erweiterung auf einer VM ausgeführt wird oder warum ein Erweiterungsprozess beendet wurde.

Hinweis

Bevor Sie Probleme mit VM-Erweiterungen auf Ihren VMs beheben, müssen die folgenden Voraussetzungen erfüllt sein:

  • Prüfen Sie, ob Sie die erforderlichen Berechtigungen haben, um Erweiterungsrichtlinien, Metadaten für Erweiterungen, die vom VM Extension Manager unterstützt werden, und VM-Erweiterungsstatus in Ihrer Google Cloud Ressourcenhierarchie zu prüfen. Weitere Informationen finden Sie unter Details und Status von VM-Erweiterungen ansehen.
  • Wenn Sie Installationsfehler, Abstürze oder Rollbacks erkennen möchten, bevor Sie eine Verbindung zu einzelnen VMs herstellen, prüfen Sie die historischen Ereignisse zur Durchsetzung von Erweiterungen in Cloud Logging. Weitere Informationen finden Sie unter VM-Erweiterungslogs ansehen.
  • Wenn Sie laufende Erweiterungsprozesse und Debugging-Logs des Gast-Agents direkt auf einer VM prüfen möchten, müssen Sie eine Verbindung zur VM über SSH oder RDP herstellen können.

Prüfen, ob eine Erweiterung installiert ist

Wenn Sie prüfen möchten, ob eine Erweiterung auf einer Compute Engine-VM installiert ist und ausgeführt wird, können Sie den Status der VM-Erweiterung mit den schreibgeschützten Methoden prüfen. Stellen Sie nur dann eine Verbindung zur VM her, wenn Sie Details zu Prozessen oder Logs des Gastbetriebssystems benötigen.

VM-Erweiterungsstatus mit schreibgeschützten Methoden prüfen

Wenn Sie den Laufzeitstatus und den Systemzustand installierter Erweiterungen prüfen möchten, ohne eine Verbindung zur VM herzustellen, führen Sie den Befehl gcloud beta compute instances list-vm-extension-states oder gcloud beta compute instances get-vm-extension-state aus oder rufen Sie die entsprechenden REST API-Methoden auf. Die Antwort enthält die aktive Version jeder Erweiterung, den Erzwingungsstatus (enforcementState), den Integritätsstatus (healthStatus), die Diagnosemeldung (healthMsg) und die ID der geltenden Richtlinie (policyId). Weitere Informationen finden Sie unter VM-Erweiterungsstatus auf einer Instanz ansehen.

Ausgeführte Erweiterungsprozesse auf der VM prüfen

Wenn Remote-Statusabfragen nicht den erwarteten Status zurückgeben, stellen Sie eine Verbindung zur VM her und prüfen Sie, ob der Erweiterungsprozess im Gastbetriebssystem ausgeführt wird.

In der folgenden Tabelle sind die Prozessnamen für die einzelnen unterstützten Erweiterungen aufgeführt:

Name der Erweiterung Name des Erweiterungsprozesses
google-cloud-sap-extension google_cloud_sap_agent
google-cloud-workload-extension google_cloud_workload_agent
ops-agent ops_agent

Wählen Sie Ihr Betriebssystem aus, um zu prüfen, ob der Erweiterungsprozess auf Ihrer VM ausgeführt wird:

Linux

Führen Sie den folgenden Befehl aus, um den laufenden Erweiterungsprozess aufzulisten:

ps aux | grep 'EXTENSION_PROCESS_NAME'
 Ersetzen Sie EXTENSION_PROCESS_NAME durch den Prozessnamen der Erweiterung aus der vorherigen Tabelle. Führen Sie beispielsweise den folgenden Befehl aus, um den Erweiterungsprozess ops-agent aufzulisten: 
ps aux | grep 'ops_agent'

Windows

Führen Sie den folgenden Befehl aus, um den laufenden Erweiterungsprozess aufzulisten:

tasklist | findstr "EXTENSION_PROCESS_NAME"
 Ersetzen Sie EXTENSION_PROCESS_NAME durch den Prozessnamen der Erweiterung aus der vorherigen Tabelle. Führen Sie beispielsweise den folgenden Befehl aus, um den Erweiterungsprozess ops-agent aufzulisten: 
tasklist | findstr "ops_agent"

Das folgende Snippet zeigt eine Beispielausgabe des Befehls ps, wenn die Erweiterung ops-agent auf einer Linux-VM ausgeführt wird:

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

Einträge zur Installation des Gast-Agents prüfen

Wenn Sie prüfen möchten, wann der Gast-Agent ein Erweiterungs-Plug-in heruntergeladen, extrahiert und gestartet hat, aktivieren Sie die Debugging-Logs für den Gast-Agent und rufen Sie sie auf.

Das folgende Snippet zeigt beispielhafte Logeinträge des Gast-Agents, wenn der Gast-Agent die Erweiterung ops-agent auf einer Linux-VM installiert und startet:

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"

Installationsprobleme beheben

Wenn eine Erweiterung nicht auf einer VM installiert ist oder eine unerwartete Erweiterung auf einer VM ausgeführt wird, diagnostizieren Sie den Richtlinien-Rollout, die Ziellabels und den Erzwingungsstatus, bevor Sie die Installation noch einmal versuchen.

Führen Sie die folgenden Diagnoseschritte aus, um herauszufinden, warum eine Erweiterung nicht auf einer VM installiert werden konnte:

  1. Warten Sie, bis die Richtlinienmaßnahme umgesetzt wird. Das Roll-out einer Richtlinie, einschließlich Wiederholungsversuchen, kann auf Ziel-VMs bis zu einer Stunde dauern. Weitere Informationen zum Prüfen des Rollout-Fortschritts finden Sie unter Erweiterungsrichtlinien ansehen.
  2. Prüfen Sie, ob die in der Richtlinie angegebenen Einschlusslabels mit den Labels auf der VM übereinstimmen, und prüfen Sie die Metadaten für Erweiterungen, die von VM Extension Manager unterstützt werden:
    • Informationen zum Prüfen von Richtlinienlabel-Selektoren und Prioritätsnummern in Ihrer Organisation, Ihrem Ordner oder Ihrem Projekt finden Sie unter Erweiterungsrichtlinien ansehen.
    • Informationen zu den Namen, Versionsnummern und Supportstufen von Erweiterungen, die VM Extension Manager in allen Zonen oder in einer bestimmten Zone unterstützt, finden Sie unter VM-Erweiterungen und -Versionen ansehen.
  3. Wenn Sie den Erzwingungsstatus, den Systemzustand, die Diagnosemeldung und die ID der geltenden Richtlinie (policyId) prüfen möchten, sehen Sie sich den Erweiterungsstatus auf der betroffenen VM an. Häufige Fehlerstatus sind INSTALL_FAILED, INCOMPATIBLE und ROLLED_BACK. Wenn mehrere Richtlinien auf dieselbe VM abzielen, wird im Feld policyId angezeigt, welche Richtlinie für die jeweilige Erweiterung gilt. Weitere Informationen finden Sie unter VM-Erweiterungsstatus auf einer Instanz ansehen.
  4. Wenn Sie Installationsfehler auf Gastebene auf der VM identifizieren möchten, aktivieren Sie die Debugging-Logs für den Gast-Agent und rufen Sie sie auf.

Installation der Erweiterung wiederholen

Nachdem Sie das Problem mit der zugrunde liegenden Richtlinienkonfiguration oder dem Gastbetriebssystem behoben haben, wenden Sie die Richtlinienkonfiguration noch einmal an, damit der Gast-Agent die Installation auf den betroffenen VMs noch einmal versucht.

Wählen Sie eine der folgenden Optionen aus, um die Installation der Erweiterung noch einmal zu versuchen:

  • Richtlinie neu erstellen: Löschen Sie die Richtlinie und erstellen Sie dann eine neue Richtlinie.

  • Temporäre Richtlinie mit höherer Priorität anwenden: Wenn Sie die Installation auf bestimmten VMs wiederholen möchten, ohne eine Richtlinie neu zu erstellen, die sich auf eine große Anzahl von VMs auswirkt, führen Sie die folgenden Schritte aus:

    1. Fügen Sie den VMs, auf denen die Installation fehlgeschlagen ist, ein temporäres Label hinzu, z. B. status=failed.

    2. Erstellen Sie eine temporäre Richtlinie mit einer höheren Priorität (einem niedrigeren Ganzzahlwert), die auf das temporäre Label abzielt. Wenn die ursprüngliche Richtlinie beispielsweise die Standardpriorität 1000 verwendet, führen Sie den folgenden Befehl aus, um eine temporäre Richtlinie mit der Priorität 500 zu erstellen:

      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. Nachdem der Gast-Agent die Erweiterung auf den Ziel-VMs installiert hat, löschen Sie die temporäre Richtlinie.

    4. Entfernen Sie das temporäre Label von den VMs. Die Erweiterung bleibt installiert, da die ursprüngliche Richtlinie weiterhin für diese VMs gilt.

Debugging-Logs für den Gast-Agent aufrufen

Wenn aus Remote-Statusabfragen und Logging-Ereignisprotokollen nicht hervorgeht, warum eine Erweiterung nicht heruntergeladen oder gestartet werden konnte, aktivieren Sie das ausführliche Debugging-Logging im Abschnitt Core der Konfigurationsdatei des Gast-Agents.

Wählen Sie Ihr Betriebssystem aus, um Debug-Logs für den Gast-Agent zu aktivieren und aufzurufen:

Linux

Führen Sie die folgenden Schritte aus, um das Debug-Logging auf einer Linux-VM zu aktivieren:

  1. Öffnen Sie die Konfigurationsdatei des Gast-Agents unter /etc/default/instance_configs.cfg.

  2. Fügen Sie in /etc/default/instance_configs.cfg die folgenden Einstellungen hinzu. Wenn der Abschnitt [Core] bereits vorhanden ist, fügen Sie log_level und log_verbosity unter [Core] hinzu:

    [Core]
log_level = 4
log_verbosity = 4

  3. Führen Sie den folgenden Befehl aus, um den Gast-Agent-Manager neu zu starten:

    sudo systemctl restart google-guest-agent-manager

  4. Führen Sie den folgenden Befehl aus, um die Gast-Agent-Logs aufzurufen, die während der Installation der Erweiterung generiert werden:

    journalctl -u google-guest-agent-manager

Windows

Führen Sie die folgenden Schritte aus, um das Debug-Logging auf einer Windows-VM zu aktivieren:

  1. Öffnen Sie die Konfigurationsdatei des Gast-Agents unter C:\Program Files\Google\Compute Engine\instance_configs.cfg.

  2. Fügen Sie in instance_configs.cfg die folgenden Einstellungen hinzu. Wenn der Abschnitt [Core] bereits vorhanden ist, fügen Sie log_level und log_verbosity unter [Core] hinzu:

    [Core]
log_level = 4
log_verbosity = 4

  3. Führen Sie in einer Eingabeaufforderung mit erhöhten Rechten oder in einem PowerShell-Fenster die folgenden Befehle aus, um den Gast-Agent-Manager neu zu starten:

    net stop GCEAgentManager
net start GCEAgentManager

  4. Führen Sie in PowerShell den folgenden Befehl aus, um die Gast-Agent-Logs aufzurufen, die während der Erweiterungsinstallation generiert werden:

    Get-Eventlog -Source google_guest_agent_manager -LogName Application

Häufige Fehler im Gast-Agent-Protokoll beheben

Prüfen Sie die Debugging-Logs des Gast-Agents auf Fehler aufgrund von Ressourcenbeschränkungen, die verhindern, dass Erweiterungen auf der VM extrahiert oder ausgeführt werden.

In der folgenden Tabelle sind häufige Fehler aufgeführt, die in den Debugging-Logs des Gast-Agents gemeldet werden, sowie deren Behebung:

Fehlerbedingung Lösung
Nicht genügend Speicherplatz Wenn in den Logs angegeben ist, dass die VM nicht genügend Speicherplatz zum Herunterladen oder Extrahieren des Erweiterungsarchivs hat, löschen Sie nicht verwendete Dateien oder passen Sie die Größe des Bootlaufwerks an.
Übermäßige Ressourcennutzung Wenn die Logs darauf hinweisen, dass der Gast-Agent die Erweiterung aufgrund einer hohen Arbeitsspeicher- oder CPU-Auslastung beendet hat, ändern Sie den Maschinentyp der VM in einen Typ mit mehr Arbeitsspeicher oder vCPUs.

Nächste Schritte