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 Compute Engine tramite l'elenco della directory dei metadati scheduling/ e la chiave dei metadati maintenance-event. Puoi utilizzare queste chiavi dei metadati per scoprire le opzioni di pianificazione di una VM e per ricevere una notifica di un evento di manutenzione imminente.

Il server di metadati riceve le notifiche degli eventi di manutenzione prima che venga eseguita la migrazione live o che venga terminata un'istanza di Compute. Per scoprire 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 saperne di più, consulta Monitora e pianifica un evento di manutenzione dell'host.

Prima di iniziare

  • Per le VM Windows Server, utilizza PowerShell 3.0 o una versione successiva. Ti consigliamo di utilizzare ctrl+v per incollare i blocchi di codice copiati.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . 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 in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.

    2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente: 

      gcloud auth application-default login

      Non devi eseguire questa operazione se utilizzi Cloud Shell.

      Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Ricevi notifiche di migrazione live

Puoi scoprire quando sta per verificarsi la migrazione live per la tua istanza eseguendo periodicamente una query sulla chiave dei 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 dei 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 una query sulla chiave dei metadati maintenance-event o non hai eseguito una query sulla chiave dei metadati dall'ultima migrazione, Compute Engine presuppone che la VM non richieda un preavviso 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 esegua una query sulla chiave dei metadati maintenance-event almeno una volta tra gli eventi di migrazione. Devi eseguire una query sulla chiave dei metadati maintenance-event direttamente per consentire a Compute Engine di determinare che stai monitorando questa chiave dei metadati. L'esecuzione di una query su metadati di livello superiore non attiva il preavviso.

Per le VM con GPU collegate, il valore cambia 60 minuti prima dell'arresto delle VM per darti il tempo di arrestarle e riavviarle su un altro host. Non viene eseguita la migrazione live delle VM con GPU collegate, ma vengono arrestate e, facoltativamente, riavviate. Per saperne di più, consulta Gestisci gli eventi di manutenzione dell'host GPU.

Esegui una query sulla chiave dei metadati dell'evento di manutenzione

VM Linux

Per eseguire una query sulla chiave dei metadati maintenance-event sulle VM Linux, esegui il seguente comando:

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

L'output è simile al seguente:

NONE

Puoi anche utilizzare l' wait-for-change opzione. Se questa opzione è specificata, la richiesta restituisce un output solo quando un evento di manutenzione sta per iniziare e terminare.

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

VM Windows

Per eseguire una query sulla chiave dei metadati maintenance-event sulle VM Windows, esegui il seguente comando:

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

L'output è simile al seguente:

NONE

Puoi anche utilizzare l' wait-for-change opzione. Se questa opzione è specificata, la richiesta restituisce un output solo quando un evento di manutenzione sta per iniziare e terminare.

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

Puoi utilizzare la chiave dei metadati maintenance-event con la funzionalità di attesa degli aggiornamenti per inviare una notifica agli script e alle applicazioni quando un evento di manutenzione sta per iniziare e terminare. In questo modo puoi automatizzare le azioni che potresti voler eseguire prima o dopo l'evento.

Il seguente esempio di Python mostra come implementare queste due funzionalità insieme.

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

Esamina 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, evento di manutenzione il valore cambia da NONE a TERMINATE_ON_HOST_MAINTENANCE. Questo valore viene aggiornato 60 minuti prima dell'inizio dell'evento di arresto.

  • Per le VM non GPU con un'opzione di pianificazione migrate, il valore di 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 arresto.
    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 single-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 una 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"
}

Per determinare quanto tempo prima di un evento di manutenzione viene compilata la chiave dei metadati upcoming-maintenance, consulta la documentazione "Esperienza di manutenzione" per la serie di macchine. Ad esempio, per i tipi di macchine Z3, consulta Esperienza di manutenzione per le istanze Z3.

Passaggi successivi