Cette page a été traduite par l'API Cloud Translation.

Interroger le serveur de métadonnées pour obtenir des notifications d'événements de maintenance

Linux Windows

Le serveur de métadonnées fournit des informations sur les options et paramètres de planification d'une instance Compute Engine via le répertoire de métadonnées scheduling/ et la clé de métadonnées maintenance-event. Vous pouvez utiliser ces clés de métadonnées pour en savoir plus sur les options de planification d'une VM et être informé d'un événement de maintenance à venir.

Le serveur de métadonnées reçoit des notifications d'événements de maintenance avant la migration à chaud ou l'arrêt d'une instance de calcul. Pour en savoir plus sur les événements de maintenance et le comportement des instances pendant les événements, consultez la section Présentation de la maintenance de l'hôte.

Pour un ensemble spécifique de VM, vos options de maintenance sont plus flexibles. Pour en savoir plus, consultez la section Surveiller et planifier un événement de maintenance de l'hôte.

Avant de commencer

Pour les VM Windows Server, utilisez PowerShell 3.0 ou version ultérieure. Nous vous recommandons d'utiliser ctrl+v pour coller les blocs de code copiés.
Si ce n'est pas déjà fait, configurez l'authentification. L'authentification est le processus permettant de valider votre identité pour accéder aux services et aux API Google Cloud. Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine en sélectionnant l'une des options suivantes:

Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.
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.
Pour en savoir plus, consultez Set up authentication for a local development environment.

Obtenir des notifications de migration à chaud

Vous pouvez savoir quand une migration à chaud est sur le point de se produire pour votre instance en interrogeant régulièrement la clé de métadonnées maintenance-event.

La clé de métadonnées maintenance-event n'est renseignée pour les événements de maintenance que si vous avez défini l'option de programmation de votre VM sur migrate ou si un GPU est associé à votre VM.

La valeur de cette clé de métadonnées change 60 secondes avant le début d'un événement de maintenance, ce qui permet au code d'application de déclencher les tâches que vous souhaitez effectuer avant l'événement de maintenance, comme la sauvegarde des données ou la mise à jour des journaux.

Compute Engine ne déclenche l'avertissement de 60 secondes que dans les cas suivants :

Vous avez défini les options de disponibilité de la VM pour la migration à chaud lors d'un événement de maintenance.
Vous avez interrogé la clé de métadonnées maintenance-event au moins une fois depuis le dernier événement de maintenance.
- Si vous n'avez jamais interrogé la clé de métadonnées maintenance-event ou si vous n'avez pas interrogé la clé de métadonnées depuis la dernière migration, Compute Engine suppose que la VM ne nécessite pas d'avertissement préalable pour les événements de maintenance. L'événement de maintenance ignore l'avertissement de 60 secondes et se déclenche immédiatement.
- Si vous ne souhaitez pas que l'avertissement de 60 secondes soit ignoré, assurez-vous que le code client interroge la clé de métadonnées maintenance-event au moins une fois entre les événements de migration. Vous devez interroger directement la clé de métadonnées maintenance-event pour que Compute Engine détermine que vous surveillez cette clé de métadonnées. L'interrogation de métadonnées de niveau supérieur ne déclenche pas la notification préalable.

Pour les VM associées à des GPU, la valeur change 60 minutes avant l'arrêt des VM pour vous donner le temps de les arrêter et de les redémarrer sur un autre hôte. Les VM avec des GPU ne sont pas migrées à chaud, mais sont arrêtées et éventuellement redémarrées. Pour en savoir plus, consultez la page Gérer les événements de maintenance de l'hôte GPU.

Interroger la clé de métadonnées d'un événement de maintenance

VM Linux

Pour interroger la clé de métadonnées maintenance-event sur des VM Linux, exécutez la commande suivante:

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

Le résultat ressemble à ce qui suit :

NONE

Vous pouvez également utiliser l'option wait-for-change. Avec cette option spécifiée, la requête ne renvoie un résultat que lorsqu'un événement de maintenance est sur le point de démarrer et de se terminer.

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

VM Windows

Pour interroger la clé de métadonnées maintenance-event sur des VM Windows, exécutez la commande suivante :

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

Le résultat ressemble à ce qui suit :

NONE

Vous pouvez également utiliser l'option wait-for-change. Lorsque cette option est spécifiée, la requête ne renvoie un résultat que lorsqu'un événement de maintenance est sur le point de démarrer et de se terminer.

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

Vous pouvez vous servir de la clé de métadonnées maintenance-event avec la fonctionnalité d'attente de mises à jour pour notifier vos scripts et applications lorsqu'un événement de maintenance est sur le point de démarrer et de se terminer. Cela vous permet d'automatiser toutes les actions que vous souhaitez exécuter avant ou après l'événement.

L'exemple Python suivant fournit un exemple de mise en œuvre de ces deux fonctionnalités.


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

Examiner les résultats

La valeur initiale et par défaut de la clé de métadonnées maintenance-event est NONE.

Pour les VM associées à des GPU, les instances bare metal ou d'autres instances qui ne sont pas compatibles avec la migration à chaud, la valeur NONE est remplacée par TERMINATE_ON_HOST_MAINTENANCE lors d'un événement de maintenance. Cette valeur est mise à jour 60 minutes avant le début de l'événement d'arrêt.
Sur les VM sans GPU disposant d'une option de programmation migrate, la valeur maintenance-event est modifiée comme suit :
1. Au début de l'événement de migration, la valeur passe de NONE à MIGRATE_ON_HOST_MAINTENANCE. Cette valeur est mise à jour 60 secondes avant le début de l'événement d'arrêt.
2. Pendant toute la durée de l'événement et pendant la migration de votre instance de VM, la valeur reste MIGRATE_ON_HOST_MAINTENANCE.
3. Une fois l'événement de maintenance terminé, la valeur revient à NONE.
Pour les VM à locataire unique, lors d'un événement de maintenance de l'hôte, la valeur de la clé de métadonnées maintenance-event ne change pas et reste NONE du début à la fin de l'événement.

Pour les séries de machines compatibles avec les fonctionnalités de maintenance avancées, vous pouvez interroger la clé de métadonnées upcoming-maintenance avant un événement de maintenance. Si une notification est disponible pour votre instance, vous devriez voir des valeurs semblables aux suivantes:

{
   "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 clé de métadonnées upcoming-maintenance est renseignée avant un événement de maintenance comme suit:

C3: jusqu'à sept jours
C3D: jusqu'à sept jours
X4: jusqu'à 60 jours
Z3: jusqu'à sept jours

Étape suivante

Découvrez comment définir les règles de disponibilité d'une instance.
En savoir plus sur la migration à chaud.
Apprenez-en plus sur les métadonnées des VM.