esegui una query sul server dei metadati per ricevere avvisi sugli 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 di metadati per conoscere le opzioni di pianificazione di una VM e anche per ricevere una notifica di un evento di manutenzione imminente.

Il server dei metadati riceve avvisi relativi agli 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 questi eventi, consulta la Panoramica della manutenzione dell'host.

Per un insieme specifico di VM, le opzioni di manutenzione delle VM sono più flessibili. A per saperne 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. Autenticazione è Il processo di verifica dell'identità per l'accesso ai servizi e alle API di Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi eseguire l'autenticazione Compute Engine come segue.

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

    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.

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

Ricevi notifiche sulla migrazione live

Puoi sapere quando sta per iniziare la migrazione live della tua istanza eseguendo periodicamente una query sulla chiave di metadati maintenance-event.

La chiave dei metadati maintenance-event viene compilata per 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 di un evento di manutenzione iniziare, assegnando al codice dell'applicazione un modo per attivare le attività che eseguire prima di un evento di manutenzione, come il backup dei dati o l'aggiornamento dei log.

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

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

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

    • Se non hai mai eseguito query su maintenance-event chiave dei metadati o non hanno eseguito query sulla chiave dei metadati dall'ultima migrazione. Compute Engine presuppone che la VM non richieda informazioni avviso di eventi di manutenzione. L'evento di manutenzione viene avviato immediatamente e ignora l'avviso di 60 secondi.

    • Se non vuoi saltare l'avviso dei 60 secondi, assicurati che il codice client esegue una query sulla chiave dei metadati maintenance-event almeno una volta tra una migrazione e l'altra eventi. Devi eseguire una query direttamente sulla chiave dei metadati maintenance-event per Compute Engine per determinare se stai guardando questa chiave di metadati. L'esecuzione di query su metadati di livello superiore non attiva il preavviso.

Per le VM con GPU collegate, il valore cambia 60 minuti prima dell'interruzione delle VM per darti il tempo di arrestare e riavviare su un altro host. La migrazione live delle VM con GPU collegate non viene eseguita, ma viene è stata interrotta e riavviata facoltativamente. Per saperne di più, vedi Gestione degli 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'opzione wait-for-change. Con 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 di metadati maintenance-event sulle VM Windows, esegui questo 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'opzione wait-for-change. Con 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 di metadati maintenance-event con in attesa di aggiornamenti per notificare gli script e le applicazioni quando si verifica un evento di manutenzione che sta per iniziare e terminare. In questo modo puoi automatizzare tutte le azioni da eseguire prima o dopo l'evento.

L'esempio di Python seguente 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 di 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 passa 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 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 inizia l'evento di interruzione.
    2. Per tutta la durata dell'evento e durante il funzionamento dell'istanza VM eseguita la migrazione live, 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, maintenance-event il valore chiave dei metadati non cambia e rimane NONE dall'inizio alla 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 vedere 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 una manutenzione come segue:

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

Passaggi successivi