Esegui query sul server dei metadati per le notifiche relative agli eventi di manutenzione

Il server di metadati fornisce informazioni sulle opzioni e sulle impostazioni di pianificazione di un'istanza di Compute Engine tramite l'elenco delle directory di metadati scheduling/ e la chiave di metadati maintenance-event. Puoi utilizzare queste chiavi di metadati per scoprire le opzioni di pianificazione di una VM e anche per ricevere una notifica di un evento di manutenzione imminente.

Il server dei metadati riceve le notifiche degli eventi di manutenzione prima che venga eseguita la migrazione live o la terminazione di un'istanza di calcolo. Per saperne di più sugli eventi di manutenzione e sul comportamento delle istanze durante gli eventi, consulta Panoramica della manutenzione dell'host.

Per un insieme specifico di VM, le opzioni di manutenzione delle VM sono più flessibili. Per scoprire di più, consulta Monitorare e pianificare un evento di manutenzione dell'host.

Prima di iniziare

• Per le VM Windows Server, utilizza PowerShell 3.0 o versioni successive. Ti consigliamo di utilizzare ctrl+v per incollare i blocchi di codice copiati.
• Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale la tua identità viene verificata per l'accesso ai Google Cloud servizi e alle API. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:
  

  Per utilizzare gli esempi di Python questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

     gcloud init

  4. 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.

     If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Per ulteriori informazioni, vedi Set up authentication for a local development environment.

Ricevere notifiche relative alla migrazione live

Puoi sapere quando sta per verificarsi la migrazione live per la tua istanza interrogando periodicamente la chiave di metadati maintenance-event.

La chiave dei metadati maintenance-event viene compilata per gli eventi di manutenzione solo se hai impostato l'opzione di pianificazione della VM su migrate o se alla VM è collegata una GPU.

Il valore di questa chiave di metadati cambia 60 secondi prima dell'inizio di un evento di manutenzione, consentendo al codice dell'applicazione di attivare le attività che vuoi eseguire prima di un evento di manutenzione, ad esempio il backup dei dati o l'aggiornamento dei log.

Compute Engine invia l'avviso di 60 secondi solo se:

• Hai impostato le opzioni di disponibilità della VM per la migrazione live durante un evento di manutenzione.

• Hai eseguito una query sulla chiave dei metadati maintenance-event almeno una volta dall'ultimo evento di manutenzione.

  • Se non hai mai eseguito query sulla chiave di metadati maintenance-event o non l'hai eseguita dall'ultima migrazione, Compute Engine presuppone che la VM non richieda l'avviso anticipato degli eventi di manutenzione. L'evento di manutenzione viene avviato immediatamente e l'avviso di 60 secondi viene ignorato.

  • Se non vuoi ignorare l'avviso di 60 secondi, assicurati che il codice client interroghi la chiave di metadati maintenance-event almeno una volta tra gli eventi di migrazione. Devi eseguire una query direttamente sulla chiave di metadati maintenance-event per Compute Engine per determinare che stai monitorando questa chiave di metadati. L'esecuzione di query su metadati di livello superiore non attiva la notifica anticipata.

Per le VM con GPU collegate, il valore cambia 60 minuti prima dell'arresto delle VM per darti il tempo di spegnerle e riavviarle su un altro host. Le VM con GPU collegate non vengono sottoposte a migrazione live, ma vengono arrestate e, facoltativamente, riavviate. Per saperne di più, consulta Gestione degli eventi di manutenzione degli host GPU.

Esegui query sulla chiave dei metadati dell'evento di manutenzione

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

NONE

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

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

NONE

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

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()

Esaminare gli output

Il valore iniziale e predefinito della chiave dei metadati maintenance-event è NONE.

• Per le VM con GPU collegate, le istanze bare metal o altre istanze che non supportano la migrazione live, il valore dell'evento di manutenzione cambia da NONE a TERMINATE_ON_HOST_MAINTENANCE. Questo valore viene aggiornato 60 minuti prima dell'inizio dell'evento di interruzione.

• Per le VM non GPU con un'opzione di pianificazione migrate, il valore maintenance-event cambia come segue:

  1. All'inizio dell'evento di migrazione, il valore cambia da NONE a MIGRATE_ON_HOST_MAINTENANCE. Questo valore viene aggiornato 60 secondi prima dell'inizio dell'evento di interruzione.
  2. Per tutta la durata dell'evento e durante la migrazione live dell'istanza VM, il valore rimane MIGRATE_ON_HOST_MAINTENANCE.
  3. Al termine dell'evento di manutenzione, il valore torna a NONE.

• Per le VM con singolo tenant, durante un evento di manutenzione dell'host, il valore della chiave dei metadati maintenance-event non cambia e rimane NONE dall'inizio alla fine dell'evento.

Per le serie di macchine che supportano funzionalità di manutenzione avanzate, prima di un evento di manutenzione puoi eseguire query sulla chiave dei metadati upcoming-maintenance. Se è disponibile una notifica per la tua istanza, dovresti visualizzare valori simili ai seguenti:

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

La chiave dei metadati upcoming-maintenance viene compilata prima di un evento di manutenzione nel seguente modo:

• C3, C3D: fino a 7 giorni
• C4D: fino a 7 giorni
• X4: fino a 60 giorni
• Z3: fino a 7 giorni

Passaggi successivi

• Scopri di più su come impostare i criteri di disponibilità delle istanze.
• Scopri di più sulla migrazione live.
• Scopri di più sui metadati della VM.