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 eine bestimmte Gruppe von VMs sind die VM-Wartungsoptionen flexibler. Weitere Informationen finden Sie unter Hostwartungsereignis überwachen und planen.

Hinweis

  • 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 Cloud de Confiance by S3NS Dienste und APIs überprüft. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei Compute Engine authentifizieren:

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

    1. Installieren Sie die Google Cloud CLI.

    2. Konfigurieren Sie die gcloud CLI für die Verwendung Ihrer föderierten Identität.

      Weitere Informationen finden Sie unter Mit Ihrer föderierten Identität in der gcloud CLI anmelden.

    3. Lokale Anmeldedaten zur Authentifizierung für Ihr Nutzerkonto erstellen: 

      gcloud auth application-default login

      Wenn ein Authentifizierungsfehler zurückgegeben wird und Sie einen externen Identitätsanbieter (IdP) verwenden, prüfen Sie, ob Sie sich mit Ihrer föderierten Identität in der gcloud CLI angemeldet haben.

    Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

Live-Migrationshinweise abrufen

Sie können erfahren, wann die Live-Migration für Ihre Instanz stattfindet, 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 etwa so aus:

NONE

Sie können auch die wait-for-change Option verwenden. Wenn diese Option angegeben ist, gibt die Anfrage nur dann eine Ausgabe zurück, wenn ein Wartungsereignis beginnt und endet.

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 wait-for-change Option verwenden. Wenn diese Option angegeben ist, gibt die Anfrage nur dann eine Ausgabe zurück, wenn ein Wartungsereignis beginnt und endet.

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 des 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 Wert des Metadatenschlüssels maintenance-event während eines Hostwartungsereignisses nicht und bleibt von Beginn bis Ende des Ereignisses NONE.

Bei Maschinenserien, die erweiterte Wartungsfunktionenunterstützen, können Sie vor einem Wartungsereignis den Metadatenschlüssel upcoming-maintenanceabfragen. Wenn eine Benachrichtigung für Ihre Instanz verfügbar ist, sollten Sie Werte ähnlich den 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"
}

Wie lange vor einem Wartungsereignis der Metadatenschlüssel upcoming-maintenance ausgefüllt wird, erfahren Sie in der Dokumentation zur Wartung für die Maschinenserie. Informationen zu Z3-Maschinentypen finden Sie beispielsweise unter Wartung für Z3-Instanzen.

Nächste Schritte