Consultar o servidor de metadados para avisos de eventos de manutenção

O servidor de metadados fornece informações sobre as opções e configurações de programação de uma instância do Compute Engine, usando a listagem do diretório de metadados scheduling/ e a chave de metadados maintenance-event. Use essas chaves de metadados para saber mais sobre as opções de programação de uma VM e também para receber uma notificação sobre um evento de manutenção.

O servidor de metadados recebe avisos de eventos de manutenção antes que uma instância de computação seja migrada em tempo real ou encerrada. Para saber mais sobre eventos de manutenção e comportamento da instância durante os eventos, consulte Visão geral da manutenção do host.

Para um conjunto específico de VMs, as opções de manutenção de VMs são mais flexíveis. Para saber mais, consulte Monitorar e planejar um evento de manutenção do host.

Antes de começar

  • Para VMs do Windows Server, use o PowerShell 3.0 ou posterior. Recomendamos que você use ctrl+v para colar os blocos de código copiados.
  • Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

    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.

    Confira mais informações em Set up authentication for a local development environment.

Receber avisos de migração em tempo real

É possível saber quando a migração em tempo real está prestes a acontecer na sua instância consultando a chave de metadados maintenance-event periodicamente.

A chave de metadados maintenance-event será preenchida para eventos de manutenção somente se você tiver definido a opção de programação da VM como migrate ou se a VM tiver uma GPU anexada.

O valor dessa chave de metadados muda 60 segundos antes do início do evento de manutenção. Assim, o código do aplicativo consegue acionar qualquer tarefa que você queira executar antes de um evento de manutenção, como fazer backup de dados ou atualizar registros.

O Compute Engine dá um aviso de 60 segundos somente nestas circunstâncias:

  • As opções de disponibilidade da instância foram definidas como migração em tempo real durante um evento de manutenção.

  • Você consultou a chave de metadados maintenance-event pelo menos uma vez desde o último evento de manutenção.

    • Se você nunca consultou a chave de metadados maintenance-event ou não fez essa consulta desde a última migração, o Compute Engine pressupõe que a VM não exige aviso prévio para eventos de manutenção. O evento de manutenção é iniciado imediatamente e ignora o aviso de 60 segundos.

    • Se você não quiser ignorar o aviso de 60 segundos, verifique se o código do cliente está consultando a chave de metadados maintenance-event pelo menos uma vez entre os eventos de migração. Consulte a chave de metadados maintenance-event diretamente para o Compute Engine determinar que você está assistindo a essa chave de metadados. Consultar metadados de nível superior não aciona o aviso antecipado.

Para VMs com GPUs anexadas, o valor muda 60 minutos antes de as VMs serem interrompidas. Assim, você tem tempo de encerrar e reiniciar em outro host. As VMs com GPUs anexadas não são migradas em tempo real, mas são interrompidas e reiniciadas opcionalmente. Saiba mais em Como lidar com eventos de manutenção do host da GPU.

Consultar a chave de metadados do evento de manutenção

VMs do Linux

Para consultar a chave de metadados maintenance-event em VMs do Linux, execute o seguinte comando:

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

O resultado será assim:

NONE

Também é possível usar a opção wait-for-change. Com essa opção especificada, a solicitação só retorna uma saída quando um evento de manutenção está prestes a começar e terminar.

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

VM do Windows

Para consultar a chave de metadados maintenance-event nas VMs do Windows, execute o seguinte comando:

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

O resultado será assim:

NONE

Também é possível usar a opção wait-for-change. Com essa opção especificada, a solicitação só retorna uma saída quando um evento de manutenção está prestes a começar e terminar.

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

Use a chave de metadados maintenance-event com o recurso aguardando atualizações para notificar os scripts e aplicativos quando um evento de manutenção estiver prestes a começar e terminar. Assim, é possível automatizar qualquer ação que você queira executar antes ou depois do evento.

Veja na amostra em Python a seguir como implementar esses dois recursos conjuntamente.


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

Analisar os resultados

O valor inicial e o padrão da chave de metadados maintenance-event é NONE.

  • Para VMs com GPUs anexadas, instâncias bare metal ou outras instâncias que não oferecem suporte à migração em tempo real, o evento de manutenção muda o valor de NONE para TERMINATE_ON_HOST_MAINTENANCE. Esse atributo é atualizado 60 minutos antes do início do evento de interrupção.

  • Para VMs que não são de GPU, mas têm uma opção de programação de migrate, o valor de maintenance-event muda da seguinte maneira:

    1. No início do evento de migração, o valor muda de NONE para MIGRATE_ON_HOST_MAINTENANCE. Esse valor é atualizado 60 segundos antes do início do evento de interrupção.
    2. Durante o evento e enquanto a instância de VM está sendo migrada, o valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
    3. Após o término do evento de manutenção, o valor volta a ser NONE.

  • Para VMs de locatário individual, durante um evento de manutenção do host, o valor da chave de metadados maintenance-event não muda e permanece NONE do início ao final do evento.

Para séries de máquinas com suporte a recursos avançados de manutenção, antes de um evento de manutenção, é possível consultar a chave de metadados upcoming-maintenance. Se houver uma notificação disponível para sua instância, você verá valores semelhantes a estes:

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

A chave de metadados upcoming-maintenance é preenchida antes de um evento de manutenção da seguinte maneira:

  • C3: até 7 dias
  • C3D: até 7 dias
  • X4: até 60 dias
  • Z3: até 7 dias

A seguir