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 mediante 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 cancele. 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 VMs 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 es el proceso mediante el cual se verifica tu identidad para acceder a los servicios y las API de Google Cloud. 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 de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

    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.

    Para obtener más información, consulta Set up authentication for a local development environment.

Obtén avisos de migración en vivo

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

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 VMs 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 opción wait-for-change. 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 opción wait-for-change. Si se especifica esta opción, 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 las VMs con GPU conectadas, las instancias de Bare Metal y otras instancias que no admiten la migración en vivo, el valor del evento de mantenimiento 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.

En el caso de las series de máquinas que admiten funciones 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"
}

La clave de metadatos upcoming-maintenance se propaga antes de un evento de mantenimiento de la siguiente manera:

  • C3: Hasta 7 días
  • C3D: Hasta 7 días
  • X4: Hasta 60 días
  • Z3: Hasta 7 días

¿Qué sigue?