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

O servidor de metadados fornece informações sobre as opções e as definições de agendamento de uma instância do Compute Engine através da lista de diretórios de metadados scheduling/ e da chave de metadados maintenance-event. Pode usar estas chaves de metadados para saber mais sobre as opções de agendamento de uma VM e também para receber uma notificação sobre um evento de manutenção futuro.

O servidor de metadados recebe avisos de eventos de manutenção antes de uma instância de computação ser migrada em direto ou terminada. Para saber mais sobre eventos de manutenção e o comportamento das instâncias durante os eventos, consulte a vista geral da manutenção do anfitrião.

Para um conjunto específico de VMs, as opções de manutenção de VMs são mais flexíveis. Para saber mais, consulte o artigo Monitorize e planeie um evento de manutenção do anfitrião.

Antes de começar

  • Para VMs do Windows Server, use o PowerShell 3.0 ou posterior. Recomendamos que use ctrl+v para colar os blocos de código copiados.
  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

    Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      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.

    Para mais informações, consulte Set up authentication for a local development environment.

Receba avisos de migração ao vivo

Pode saber quando a migração em direto está prestes a ocorrer para a sua instância consultando a chave de metadados maintenance-event periodicamente.

A chave de metadados maintenance-event é preenchida para eventos de manutenção apenas se tiver definido a opção de agendamento da VM como migrate ou se a VM tiver uma GPU anexada.

O valor desta chave de metadados muda 60 segundos antes do início de um evento de manutenção, o que dá ao código da sua aplicação uma forma de acionar quaisquer tarefas que queira realizar antes de um evento de manutenção, como fazer uma cópia de segurança dos dados ou atualizar os registos.

O Compute Engine envia o aviso de 60 segundos apenas se:

  • Definiu as opções de disponibilidade da VM para migrar em direto durante um evento de manutenção.

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

    • Se nunca tiver consultado a chave de metadados ou não tiver consultado a chave de metadados desde a última migração, o Compute Engine assume que a VM não requer um aviso prévio de eventos de manutenção.maintenance-event O evento de manutenção é iniciado imediatamente e ignora o aviso de 60 segundos.

    • Se não quiser ignorar o aviso de 60 segundos, certifique-se de que o código do cliente consulta a chave de metadados maintenance-event, pelo menos, uma vez entre os eventos de migração. Tem de consultar a chave de metadados maintenance-event diretamente para que o Compute Engine determine que está a monitorizar esta chave de metadados. A consulta de metadados de nível superior não aciona o aviso prévio.

Para VMs com GPUs anexadas, o valor muda 60 minutos antes de as VMs serem paradas para lhe dar tempo de desligar e reiniciar novamente noutro anfitrião. As VMs com GPUs anexadas não são migradas em direto e, em vez disso, são paradas e, opcionalmente, reiniciadas. Para saber mais, consulte o artigo Como processar eventos de manutenção do anfitrião da GPU.

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

VMs 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 é semelhante ao seguinte:

NONE

Também pode usar a opção wait-for-change. Com esta opção especificada, o pedido só devolve um resultado 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"

VMs do Windows

Para consultar a chave de metadados maintenance-event em 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 é semelhante ao seguinte:

NONE

Também pode usar a opção wait-for-change. Com esta opção especificada, o pedido só devolve um resultado 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

Pode usar a chave de metadados maintenance-event com a funcionalidade waiting for updates para notificar os seus scripts e aplicações quando um evento de manutenção estiver prestes a começar e terminar. Isto permite-lhe automatizar quaisquer ações que queira executar antes ou depois do evento.

O seguinte exemplo de Python mostra como pode implementar estas duas funcionalidades em conjunto.

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

Reveja os resultados

O valor inicial e predefinido da chave de metadados maintenance-event é NONE.

  • Para VMs com GPUs anexadas, instâncias bare metal ou outras instâncias que não suportam a migração em direto, o valor do evento de manutenção muda de NONE para TERMINATE_ON_HOST_MAINTENANCE. Este valor é atualizado 60 minutos antes do início do evento de paragem.

  • Para VMs sem GPU com uma opção de agendamento de migrate, o valor de maintenance-event muda da seguinte forma:

    1. No início do evento de migração, o valor é alterado de NONE para MIGRATE_ON_HOST_MAINTENANCE. Este valor é atualizado 60 segundos antes do início do evento de paragem.
    2. Durante a duração do evento e enquanto a instância da VM está a ser migrada em direto, o valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
    3. Após o evento de manutenção terminar, o valor volta a ser NONE.

  • Para VMs de inquilino único, durante um evento de manutenção do anfitrião, o maintenance-event valor da chave de metadados não se altera e permanece NONE do início ao fim do evento.

Para as séries de máquinas que suportam capacidades de manutenção avançadas, antes de um evento de manutenção, pode consultar a chave de metadados upcoming-maintenance. Se existir uma notificação disponível para a sua instância, deve ver valores semelhantes aos seguintes:

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

Para determinar quanto tempo antes de um evento de manutenção a chave de metadados é preenchida, consulte a documentação "Experiência de manutenção" para a série de máquinas.upcoming-maintenance Por exemplo, para os tipos de máquinas Z3, consulte o artigo Experiência de manutenção para instâncias Z3.

O que se segue?