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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O servidor de metadados fornece informações sobre as opções e configurações de agendamento de uma instância do Compute Engine por meio da listagem do diretório scheduling/ metadados e da chave de metadados maintenance-event . Você pode usar essas chaves de metadados para saber mais sobre as opções de agendamento de uma VM e também para notificá-lo sobre um próximo 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 ou encerrada em tempo real. 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 VM são mais flexíveis. Para saber mais, consulte Monitorar e planejar um evento de manutenção de 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.
• Se ainda não o fez, configure a autenticação. Autenticação é o processo pelo qual sua identidade é verificada para acesso a Google Cloud serviços e APIs. Para executar códigos ou amostras em um ambiente de desenvolvimento local, você pode se autenticar 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. 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, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

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

Receba avisos de migração em tempo real

Você pode saber quando a migração ao vivo está prestes a acontecer para sua instância consultando periodicamente a chave de metadados maintenance-event .

A chave de metadados maintenance-event será preenchida para eventos de manutenção somente se você tiver definido a opção de agendamento da VM para 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, dando ao código do seu aplicativo uma maneira de acionar quaisquer tarefas que você deseja executar antes de um evento de manutenção, como backup de dados ou atualização de logs.

O Compute Engine fornecerá o aviso de 60 segundos somente se:

• Você definiu as opções de disponibilidade da VM para 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 consultou a chave de metadados desde a última migração, o Compute Engine pressupõe que a VM não exige aviso prévio de eventos de manutenção. 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. Você deve consultar a chave de metadados maintenance-event diretamente para que o Compute Engine determine se você está monitorando essa chave de metadados. Consultar 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 interrompidas para dar tempo para desligar e reiniciar novamente em outro host. As VMs com GPUs anexadas não são migradas em tempo real e, em vez disso, são interrompidas e opcionalmente reiniciadas. Para saber mais, consulte Tratamento de eventos de manutenção de host de GPU .

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

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

Revise as saídas

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

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

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

  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 parada.
  2. Durante todo o evento e enquanto sua instância de VM estiver sendo migrada em tempo real, o valor permanecerá como MIGRATE_ON_HOST_MAINTENANCE .
  3. Após o término do evento de manutenção, o valor retorna para NONE .

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

Para séries de máquinas que oferecem suporte a recursos avançados de manutenção , antes de um evento de manutenção, você pode consultar a chave de metadados upcoming-maintenance . Se houver uma notificação disponível para sua instância, você 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"
}

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

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

O que vem a seguir

• Saiba mais sobre como definir políticas de disponibilidade de instâncias .
• Saiba mais sobre migração em tempo real .
• Saiba mais sobre metadados de VM .