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

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

El servidor de metadatos proporciona información sobre las opciones y configuraciones de programación de una instancia de Compute Engine, a través de la lista del directorio de scheduling/ metadatos y la clave de metadatos maintenance-event . Puede utilizar estas claves de metadatos para conocer las opciones de programación de una máquina virtual y también para notificarle sobre un próximo evento de mantenimiento.

El servidor de metadatos recibe avisos de eventos de mantenimiento antes de que una instancia informática se migre en vivo o finalice. Para obtener más información sobre los eventos de mantenimiento y el comportamiento de las instancias durante los eventos, consulte Descripción general del mantenimiento del host .

Para un conjunto específico de máquinas virtuales, sus opciones de mantenimiento de máquinas virtuales son más flexibles. Para obtener más información, consulte Supervisar y planificar un evento de mantenimiento del host .

Antes de comenzar

• Para máquinas virtuales con Windows Server, utilice PowerShell 3.0 o posterior . Le recomendamos que utilice ctrl+v para pegar los bloques de código copiados.
• Si aún no lo has hecho, configura la autenticación. La autenticación es el proceso mediante el cual se verifica su identidad para acceder a Google Cloud servicios y API. 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. 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.

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

Reciba avisos de migración en vivo

Puede saber cuándo está a punto de realizarse la migración en vivo para su instancia consultando periódicamente la clave de metadatos maintenance-event .

La clave de metadatos maintenance-event se completa para los eventos de mantenimiento solo si ha configurado la opción de programación de su VM para migrate o si su VM tiene una GPU conectada.

El valor de esta clave de metadatos cambia 60 segundos antes de que comience un evento de mantenimiento, lo que le brinda al código de su aplicación una forma de activar cualquier tarea que desee realizar antes de un evento de mantenimiento, como realizar copias de seguridad de datos o actualizar registros.

Compute Engine muestra la advertencia de 60 segundos solo si:

• Ha configurado las opciones de disponibilidad de la máquina virtual para migrar en vivo 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 has consultado la clave de metadatos desde la última migración, Compute Engine asume que la VM no requiere advertencia previa de los eventos de mantenimiento. El evento de mantenimiento se inicia inmediatamente y se salta la advertencia de 60 segundos.

  • Si no desea omitir la advertencia de 60 segundos, asegúrese de que su código de cliente consulte la clave de metadatos maintenance-event al menos una vez entre eventos de migración. Debes consultar la clave de metadatos maintenance-event directamente para Compute Engine para determinar que estás observando esta clave de metadatos. La consulta de metadatos de nivel superior no activa el aviso anticipado.

Para las máquinas virtuales con GPU conectadas, el valor cambia 60 minutos antes de que se detengan las máquinas virtuales para darle tiempo a apagarse y reiniciarse nuevamente en otro host. Las máquinas virtuales con GPU conectadas no se migran en vivo, sino que se detienen y, opcionalmente, se reinician. Para obtener más información, consulte Manejo de eventos de mantenimiento del 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 .

• Para las máquinas virtuales con GPU conectadas, instancias bare metal u 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.

• Para máquinas virtuales 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. Durante la duración del evento y mientras su instancia de VM se migra en vivo, el valor permanece como MIGRATE_ON_HOST_MAINTENANCE .
  3. Una vez finalizado el evento de mantenimiento, el valor vuelve a NONE .

• Para las máquinas virtuales de inquilino único, durante un evento de mantenimiento del host, el valor de la clave de metadatos maintenance-event no cambia y permanece NONE desde el principio hasta el final del evento.

Para las series de máquinas que admiten capacidades de mantenimiento avanzadas , antes de un evento de mantenimiento puede consultar la clave de metadatos upcoming-maintenance . Si hay una notificación disponible para su instancia, debería 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 completa 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?

• Obtenga información sobre cómo configurar políticas de disponibilidad de instancias .
• Obtenga más información sobre la migración en vivo .
• Obtenga más información sobre los metadatos de VM .