Metadatenserver auf Benachrichtigungen zu Wartungsereignissen abfragen

Der Metadatenserver stellt Informationen zu den Planungsoptionen und -einstellungen einer Compute Engine-Instanz über die Metadatenverzeichnisliste scheduling/ und den Metadatenschlüssel maintenance-event bereit. Sie können diese Metadatenschlüssel verwenden, um mehr über die Planungsoptionen einer VM zu erfahren und um sich benachrichtigen zu lassen, wenn ein Wartungsereignis bevorsteht.

Der Metadatenserver erhält Benachrichtigungen für Wartungsereignisse, bevor eine Compute-Instanz live migriert oder beendet wird. Weitere Informationen zu Wartungsereignissen und dem Verhalten von Instanzen während Wartungsereignissen finden Sie unter Hostwartung – Übersicht.

Für bestimmte VMs sind die Wartungsoptionen flexibler. Weitere Informationen finden Sie unter Hostwartungsereignis überwachen und planen.

Hinweise

  • Verwenden Sie für Windows Server-VMs PowerShell 3.0 oder höher. Wir empfehlen, die kopierten Codeblöcke mit ctrl+v einzufügen.
  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud-Dienste und APIs überprüft. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich bei Compute Engine authentifizieren. Wählen Sie dazu eine der folgenden Optionen aus:

    Wenn Sie die Python Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Weitere Informationen unter Set up authentication for a local development environment.

Live-Migrationshinweise abrufen

Sie können erfahren, wann eine Live-Migration für Ihre Instanz bevorsteht, indem Sie den Metadatenschlüssel maintenance-event regelmäßig abfragen.

Der Metadatenschlüssel maintenance-event wird nur für Wartungsereignisse ausgefüllt, wenn Sie die Planungsoption der VM auf migrate festgelegt haben oder eine GPU an die VM angehängt ist.

Der Wert dieses Metadatenschlüssels ändert sich 60 Sekunden, bevor eine Wartung stattfindet, sodass Ihr Anwendungscode die Möglichkeit hat, Aufgaben einzuleiten, die vor einer Wartung durchgeführt werden sollen, zum Beispiel Datensicherungen oder Logaktualisierungen.

Die Compute Engine gibt die 60-Sekunden-Warnung nur dann aus, wenn:

  • Sie die Verfügbarkeitsoptionen der VM so eingestellt haben, dass bei einem Wartungsereignis live migriert werden soll.

  • Sie den Metadatenschlüssel maintenance-event seit dem letzten Wartungsereignis mindestens einmal abgefragt haben.

    • Wenn Sie den Metadatenschlüssel maintenance-event noch nie oder seit der letzten Migration nicht mehr abgefragt haben, geht Compute Engine davon aus, dass die VM keine Warnung vor bevorstehenden Wartungsereignissen benötigt. Das Wartungsereignis wird sofort ausgeführt und überspringt die 60-Sekunden-Warnung.

    • Wenn Sie die 60-Sekunden-Warnung nicht überspringen möchten, sollten Sie darauf achten, dass Ihr Clientcode nach einer Migration mindestens einmal den Metadatenschlüssel maintenance-event abfragt. Sie müssen den Metadatenschlüssel maintenance-event direkt abfragen, damit Compute Engine erkennt, dass Sie diesen Metadatenschlüssel beobachten. Eine Abfrage übergeordneter Metadaten löst die Warnung nicht aus.

Bei VMs mit angehängten GPUs ändert sich der Wert 60 Minuten, bevor die VMs beendet werden. So haben Sie Zeit, sie herunterzufahren und auf einem anderen Host neu zu starten. VMs mit angehängten GPUs werden nicht live migriert, sondern stattdessen beendet und optional neu gestartet. Weitere Informationen finden Sie unter GPU-Hostwartungsereignisse verarbeiten.

Wartungsereignis-Metadatenschlüssel abfragen

Linux-VMs

Führen Sie den folgenden Befehl aus, um den Metadatenschlüssel maintenance-event auf Linux-VMs abzufragen:

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"

Die Ausgabe sieht in etwa so aus:

NONE

Sie können auch die Option wait-for-change verwenden. Bei dieser Option gibt die Anfrage nur dann eine Ausgabe zurück, wenn ein Wartungsereignis kurz bevorsteht oder gerade stattfindet.

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event?wait_for_change=true -H "Metadata-Flavor: Google"

Windows-VMs

Führen Sie den folgenden Befehl aus, um den Metadatenschlüssel maintenance-event auf Windows-VMs abzufragen:

PS C:\> 
$value = (Invoke-RestMethod `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event")
$value

Die Ausgabe sieht in etwa so aus:

NONE

Sie können auch die Option wait-for-change verwenden. Bei dieser Option gibt die Anfrage nur dann eine Ausgabe zurück, wenn ein Wartungsereignis kurz bevorsteht oder gerade stattfindet.

PS C:\> 
$value = (Invoke-RestMethod `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event?wait_for_change=true")
$value

Python

Sie können den Metadatenschlüssel maintenance-event mit dem Feature zum Warten auf Aktualisierungen verwenden, um eine Benachrichtigung über den Beginn und das Ende einer Wartung an Ihre Skripts und Anwendungen zu senden. So können Sie Aktionen automatisieren, die Sie vor oder nach der Wartung ausführen möchten.

Das folgende Beispiel für Python zeigt Ihnen, wie Sie die beiden Features zusammen implementieren können.


import time
from typing import Callable, NoReturn, Optional

import requests


METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/"
METADATA_HEADERS = {"Metadata-Flavor": "Google"}


def wait_for_maintenance(callback: Callable[[Optional[str]], None]) -> NoReturn:
    """
    Start an infinite loop waiting for maintenance signal.

    Args:
        callback: Function to be called when a maintenance is scheduled.

    Returns:
        Never returns, unless there's an error.
    """
    url = METADATA_URL + "instance/maintenance-event"
    last_maintenance_event = None
    last_etag = "0"

    while True:
        r = requests.get(
            url,
            params={"last_etag": last_etag, "wait_for_change": True},
            headers=METADATA_HEADERS,
        )

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers["etag"]

        if r.text == "NONE":
            maintenance_event = None
        else:
            maintenance_event = r.text

        if maintenance_event != last_maintenance_event:
            last_maintenance_event = maintenance_event
            callback(maintenance_event)


def maintenance_callback(event: Optional[str]) -> None:
    """
    Example callback function to handle the maintenance event.

    Args:
        event: details about scheduled maintenance.
    """
    if event:
        print(f"Undergoing host maintenance: {event}")
    else:
        print("Finished host maintenance")


def main():
    wait_for_maintenance(maintenance_callback)


if __name__ == "__main__":
    main()

Ausgaben prüfen

Der Start- und Standardwert des Metadatenschlüssels maintenance-event ist NONE.

  • Bei VMs mit angehängten GPUs, Bare-Metal-Instanzen oder anderen Instanzen, die keine Live-Migration unterstützen, ändert sich der Wert während eines Wartungsereignisses von NONE in TERMINATE_ON_HOST_MAINTENANCE. Dieser Wert wird 60 Minuten vor Beginn des Beendigungsereignisses aktualisiert.

  • Bei VMs ohne GPU mit der Planungsoption migrate ändert sich der Wert maintenance-event so:

    1. Zu Beginn des Migrationsereignisses ändert sich der Wert von NONE in MIGRATE_ON_HOST_MAINTENANCE. Dieser Wert wird 60 Sekunden vor Beginn des Beendigungsereignisses aktualisiert.
    2. Während des Ereignisses und während Ihre VM-Instanz live migriert wird, bleibt der Wert MIGRATE_ON_HOST_MAINTENANCE.
    3. Nach der Wartung ändert sich der Wert wieder in NONE.

  • Bei VMs für einzelne Mandanten ändert sich der Metadatenschlüsselwert maintenance-event während eines Hostwartungsereignisses nicht und bleibt vom Beginn bis zum Ende des Ereignisses NONE.

Bei Gerätereihen, die erweiterte Wartungsfunktionen unterstützen, können Sie vor einem Wartungsereignis den Metadatenschlüssel upcoming-maintenance abfragen. Wenn für Ihre Instanz eine Benachrichtigung verfügbar ist, sollten Sie ähnliche Werte wie die folgenden sehen:

{
   "maintenanceType":"SCHEDULED"
   "canReschedule": "true"
   "latestWindowStartTime": "2025-08-28T21:56:21Z"
   "maintenanceStatus": "PENDING"
   "windowEndTime": "2025-08-29T01:56:20Z"
   "windowStartTime": "2025-08-28T21:56:26Z"
}

Der Metadatenschlüssel upcoming-maintenance wird vor einem Wartungsereignis so ausgefüllt:

  • C3: bis zu 7 Tage
  • C3D: bis zu 7 Tage
  • X4: bis zu 60 Tage
  • Z3: bis zu 7 Tage

Nächste Schritte