Consultar el servidor de metadatos para obtener avisos de eventos de mantenimiento

El servidor de metadatos proporciona información sobre las opciones y los ajustes de programación de una instancia de Compute Engine a través del listado de directorios de metadatos scheduling/ y de la clave de metadatos maintenance-event. Puede usar estas claves de metadatos para obtener información sobre las opciones de programación de una VM y para recibir notificaciones sobre un evento de mantenimiento próximo.

El servidor de metadatos recibe avisos de eventos de mantenimiento antes de que se migre o se termine una instancia de computación. Para obtener más información sobre los eventos de mantenimiento y el comportamiento de las instancias durante estos eventos, consulte el artículo Descripción general del mantenimiento del host.

En el caso de un conjunto específico de VMs, las opciones de mantenimiento de VMs son más flexibles. Para obtener más información, consulta el artículo Monitorizar y planificar un evento de mantenimiento del host.

Antes de empezar

• En el caso de las máquinas virtuales de Windows Server, usa PowerShell 3.0 o una versión posterior. Te recomendamos que uses ctrl+v para pegar los bloques de código copiados.
• Si aún no lo has hecho, configura la autenticación. La autenticación verifica tu identidad para acceder a Google Cloud servicios y APIs. Para ejecutar código o ejemplos desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

  Para usar las Python muestras de esta página en un entorno de desarrollo local, instala e inicializa la CLI de gcloud y, a continuación, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  Instala Google Cloud CLI.

  Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad 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 obtener más información, consulta Set up authentication for a local development environment.

Recibir notificaciones de migración en tiempo real

Puedes saber cuándo se va a producir la migración en directo de tu instancia consultando la clave de metadatos maintenance-event periódicamente.

La clave de metadatos maintenance-event se rellena en los eventos de mantenimiento solo si has definido la opción de programación de tu VM como migrate o si tu VM tiene una GPU conectada.

El valor de esta clave de metadatos cambia 60 segundos antes de que empiece un evento de mantenimiento, lo que permite que el código de tu aplicación active las tareas que quieras realizar antes de un evento de mantenimiento, como crear copias de seguridad de los datos o actualizar los registros.

Compute Engine solo envía la advertencia de 60 segundos si se cumplen las siguientes condiciones:

• Has configurado las opciones de disponibilidad de la VM para que se migre automáticamente durante un evento de mantenimiento.

• Ha consultado la clave de metadatos maintenance-event al menos una vez desde el último evento de mantenimiento.

  • Si nunca has consultado la clave de metadatos maintenance-event o no lo has hecho desde la última migración, Compute Engine asume que la VM no requiere una advertencia anticipada de los eventos de mantenimiento. El evento de mantenimiento se inicia inmediatamente y se salta la advertencia de 60 segundos.

  • Si no quieres saltarte la advertencia de 60 segundos, asegúrate de que tu código de cliente consulte la clave de metadatos maintenance-event al menos una vez entre eventos de migración. Debes consultar directamente la clave de metadatos maintenance-event para que Compute Engine determine que estás monitorizando esta clave de metadatos. Consultar metadatos de un nivel superior no activa el aviso.

En el caso de las máquinas virtuales con GPUs conectadas, el valor cambia 60 minutos antes de que se detengan las máquinas virtuales para que tengas tiempo de apagarlas y reiniciarlas en otro host. Las VMs con GPUs conectadas no se migran en directo, sino que se detienen y, opcionalmente, se reinician. Para obtener más información, consulta Gestionar eventos de mantenimiento de host de GPU.

Consultar la clave de metadatos del evento de mantenimiento

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

Revisar los resultados

El valor inicial y predeterminado de la clave de metadatos maintenance-event es NONE.

• En el caso de las máquinas virtuales con GPUs conectadas, las instancias de hardware desnudo u otras instancias que no admitan la migración activa, el valor de maintenance event cambia de NONE a TERMINATE_ON_HOST_MAINTENANCE. Este valor se actualiza 60 minutos antes de que empiece el evento de detención.

• En las VMs sin GPU con la opción de programación migrate, el valor de maintenance-event cambia de la siguiente manera:

  1. Al inicio del evento de migración, el valor cambia de NONE a MIGRATE_ON_HOST_MAINTENANCE. Este valor se actualiza 60 segundos antes de que empiece el evento de detención.
  2. Durante el evento y mientras se migra en directo tu instancia de VM, el valor sigue siendo MIGRATE_ON_HOST_MAINTENANCE.
  3. Cuando finalice el evento de mantenimiento, el valor volverá a ser NONE.

• En las VMs de un solo inquilino, durante un evento de mantenimiento del host, el valor de la clave de metadatos maintenance-event no cambia y sigue siendo NONE desde el inicio hasta el final del evento.

En las series de máquinas que admiten funciones de mantenimiento avanzadas, puedes consultar la clave de metadatos upcoming-maintenance antes de un evento de mantenimiento. Si hay una notificación disponible para tu instancia, deberías ver valores similares a los siguientes:

{
   "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 cuánto tiempo antes de un evento de mantenimiento se rellena la clave de metadatos upcoming-maintenance, consulta la documentación "Experiencia de mantenimiento" de la serie de la máquina. Por ejemplo, en el caso de los tipos de máquinas Z3, consulta Mantenimiento de instancias Z3.

Siguientes pasos

• Consulta cómo configurar políticas de disponibilidad de instancias.
• Consulta cómo simular un evento de mantenimiento del anfitrión.
• Consulta más información sobre la migración en directo.
• Más información sobre los metadatos de máquinas virtuales