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

El servidor de metadatos proporciona información sobre las opciones y la configuración de programación de una instancia de Compute Engine a través de la lista del directorio de metadatos scheduling/ y la clave de metadatos maintenance-event. Puedes usar estas claves de metadatos para obtener información sobre las opciones de programación de una VM y para notificarte sobre un próximo evento de mantenimiento.

El servidor de metadatos recibe notificaciones de eventos de mantenimiento antes de que una instancia de procesamiento se migre en vivo o se finalice. Para obtener más información sobre los eventos de mantenimiento y el comportamiento de la instancia durante estos eventos, consulta Descripción general del mantenimiento del host.

Para un conjunto específico de VMs, las opciones de mantenimiento de VM son más flexibles. Para obtener más información, consulta Supervisa y planifica un evento de mantenimiento del host.

Antes de comenzar

  • Para VM de Windows Server, usa PowerShell 3.0 o versiones posteriores. Te recomendamos que uses ctrl+v para pegar los bloques de código copiados.
  • Si aún no lo hiciste, configura la autenticación. La autenticación verifica tu identidad para acceder a los Google Cloud servicios y las APIs. Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

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

    1. Instala Google Cloud CLI.

    2. Si usas un proveedor de identidad (IdP) externo, primero debes acceder a la gcloud CLI con tu identidad federada.

    3. Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario: 

      gcloud auth application-default login

      No es necesario que lo hagas si usas Cloud Shell.

      Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

    Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

Obtén avisos de migración en vivo

Puedes saber cuándo ocurrirá la migración en vivo de tu instancia si consultas de forma periódica la clave de metadatos maintenance-event.

La clave de metadatos maintenance-event se propaga para los eventos de mantenimiento solo si configuraste la opción de programación de la VM como migrate o si la VM tiene una GPU conectada.

El valor de esta clave de metadatos cambia 60 segundos antes de que se inicie un evento de mantenimiento, lo que le da al código de la aplicación una forma de activar cualquier tarea que desees realizar antes de un evento de mantenimiento, como crear una copia de seguridad de los datos o actualizar registros.

Compute Engine da la advertencia de 60 segundos solo si se cumplen estas condiciones:

  • Si estableciste las opciones de disponibilidad de la VM para la migración en vivo durante un evento de mantenimiento.

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

    • Si nunca consultaste la clave de metadatos maintenance-event o no la hiciste desde la última migración, Compute Engine supone que la VM no requiere una advertencia previa a los eventos de mantenimiento. El evento de mantenimiento se inicia de inmediato y omite la advertencia de 60 segundos.

    • Si no deseas omitir la advertencia de 60 segundos, asegúrate de que el código del cliente consulte la clave de metadatos maintenance-event al menos una vez entre los eventos de migración. Debes consultar la clave de metadatos maintenance-event directamente para Compute Engine a fin de determinar si la estás mirando. Consultar metadatos de nivel superior no activa la notificación previa.

En el caso de las VM con GPU conectadas, el valor cambia 60 minutos antes de que se detengan las VM a fin de que tengas tiempo de apagar y reiniciar en otro host. Las VM con GPU conectadas no se migran en vivo, en su lugar se detienen y se reinician de forma opcional. Para obtener más información, consulta Controla eventos de mantenimiento del host de la GPU.

Consulta la clave de metadatos del evento de mantenimiento

VM de Linux

Para consultar la clave de metadatos maintenance-event en las VM de Linux, ejecuta el siguiente comando:

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

El resultado es similar a este:

NONE

También puedes usar la wait-for-change opción. Con esta opción especificada, la solicitud solo muestra un resultado cuando un evento de mantenimiento está por comenzar y finalizar.

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

VM de Windows

Para consultar la clave de metadatos maintenance-event en las VM de Windows, ejecuta el siguiente comando:

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

El resultado es similar a este:

NONE

También puedes usar la wait-for-change opción. Con esta opción especificada, la solicitud solo muestra un resultado cuando un evento de mantenimiento está por comenzar y finalizar.

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

Puedes usar la clave de metadatos maintenance-event con la función de espera de actualizaciones para notificar a tus secuencias de comandos y aplicaciones cuando un evento de mantenimiento esté por comenzar y finalizar. Esto te permite automatizar cualquier acción que desees ejecutar antes o después del evento.

La muestra siguiente de Python proporciona un ejemplo de cómo puedes implementar estas dos funciones.

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

Revisa los resultados

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

  • En el caso de las VMs con GPU conectadas, las instancias de Bare Metal o cualquier otra instancia que no admita la migración en vivo, el evento de mantenimiento el valor cambia de NONE a TERMINATE_ON_HOST_MAINTENANCE. Este valor se actualiza 60 minutos antes de que comience el evento de detención.

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

    1. Al comienzo del evento de migración, el valor cambia de NONE a MIGRATE_ON_HOST_MAINTENANCE. Este valor se actualiza 60 segundos antes de que comience el evento de detención.
    2. Mientras dura el evento y la instancia de VM se migra en vivo, el valor permanece como MIGRATE_ON_HOST_MAINTENANCE.
    3. Cuando finaliza el evento de mantenimiento, el valor vuelve a ser NONE.

  • Para las VMs de usuario único, durante un evento de mantenimiento del host, el valor de la clave de metadatos maintenance-event no cambia y permanece NONE desde el inicio hasta el final del evento.

Para las series de máquinas que admiten capacidades de mantenimiento avanzadas, antes de un evento de mantenimiento, puedes consultar la clave de metadatos upcoming-maintenance. 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 propaga la clave de metadatos upcoming-maintenance, consulta la documentación de "Experiencia de mantenimiento" para la serie de máquinas. Por ejemplo, para los tipos de máquinas Z3, consulta Experiencia de mantenimiento para instancias Z3.

¿Qué sigue?