Service de métadonnées Azure : Événements planifiés pour les machines virtuelles Windows

S’applique à : ✔️ Machines virtuelles Windows ✔️ Jeux d’échelles flexibles ✔️ Jeux d’échelles uniformes

Événements planifiés est un service de métadonnées Azure qui permet à votre application de disposer de suffisamment de temps pour se préparer à la maintenance des machines virtuelles. Il fournit des informations sur les événements de maintenance à venir (par exemple, les redémarrages), afin que votre application puisse s’y préparer et limiter les interruptions de service. Il est disponible pour tous les types de machines virtuelles Azure, notamment PaaS et IaaS sur Windows et Linux.

Pour plus d’informations sur les événements planifiés sur Linux, consultez Événements planifiés pour les machines virtuelles Linux.

Notes

Le service Événements planifiés est mis à la disposition générale dans toutes les régions Azure. Consultez la section Version et disponibilité dans la région pour obtenir des informations sur la version la plus récente.

Pourquoi utiliser le service Événements planifiés ?

De nombreuses applications peuvent bénéficier d’un délai pour se préparer à la maintenance des machines virtuelles. Ce délai peut servir à effectuer des tâches propres aux applications qui améliorent la disponibilité, la fiabilité et la facilité de maintenance, notamment :

  • Point de contrôle et restauration
  • Vidage des connexions
  • Basculement du réplica principal
  • Suppression à partir du pool d’équilibreur de charge
  • Journalisation des événements
  • Arrêt approprié

Avec le service Événements planifiés, votre application peut savoir quand une maintenance a lieu et déclencher des tâches pour limiter son impact.

Le service Événements planifiés fournit des événements dans les cas d’usage suivants :

Concepts de base

Le service de métadonnées expose des informations sur les machines virtuelles en cours d’exécution en utilisant un point de terminaison REST accessible depuis la machine virtuelle. Ces informations sont disponibles via une adresse IP non routable, de façon à ce qu’elles ne soient pas exposées en dehors de la machine virtuelle.

Étendue

Les événements planifiés sont remis à :

  • Machines virtuelles autonomes.
  • Toutes les machines virtuelles d’un service cloud
  • Toutes les machines virtuelles d’un groupe à haute disponibilité
  • Toutes les machines virtuelles d’une zone à haute disponibilité.
  • Toutes les machines virtuelles d’un groupe de placement de groupe identique

Notes

Les événements planifiés pour toutes les machines virtuelles d’un locataire de contrôleur de structure (FC) sont remises à toutes les machines virtuelles d’un locataire de contrôleur de structure. Le locataire de contrôleur de structure correspond à une machine virtuelle autonome, à un service Cloud entier, à un groupe à haute disponibilité et à un groupe de placement pour un groupe de machines virtuelles identiques (VMSS), quelle que soit l’utilisation des zones de disponibilité.

Par conséquent, vérifiez le champ Resources de l’événement pour identifier les machines virtuelles concernées.

Découverte de point de terminaison

Pour les machines virtuelles compatibles avec le réseau virtuel, le service de métadonnées est disponible à partir d’une adresse IP non routable statique, 169.254.169.254. Le point de terminaison complet de la dernière version des événements planifiés est :

http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01

Si la machine virtuelle n’est pas créée au sein d’un réseau virtuel, ce qui est habituellement le cas pour les services cloud et les machines virtuelles classiques, une logique supplémentaire est nécessaire pour découvrir l’adresse IP à utiliser. Reportez-vous à cet exemple pour savoir comment découvrir le point de terminaison hôte.

Version et disponibilité dans la région

Les versions du service Événements planifiés sont gérées. Ces versions sont obligatoires et la version actuelle est 2020-07-01.

Version Type de version Régions Notes de publication
2020-07-01 Disponibilité générale Tous
  • Ajout de la prise en charge pour Durée de l’événement
  • 2019-08-01 Disponibilité générale Tous
  • Ajout de la prise en charge pour EventSource
  • 2019-04-01 Disponibilité générale Tous
  • Ajout de la prise en charge pour Description de l’événement
  • 2019-01-01 Disponibilité générale Tous
  • Ajout de la prise en charge des groupes de machines virtuelles identiques, EventType « Terminate »
  • 2017-11-01 Disponibilité générale Tous
  • Ajout de la prise en charge de l’éviction de machine virtuelle Spot, EventType « Preempt »
  • 2017-08-01 Disponibilité générale Tous
  • Suppression du trait de soulignement ajouté au début des noms de ressources pour les machines virtuelles IaaS
  • Spécification d’en-tête de métadonnées appliquée à toutes les requêtes
  • 2017-03-01 PRÉVERSION Tous
  • Version initiale
  • Notes

    Les préversions précédentes du service Evénements planifiés prenaient en charge {latest} en tant que version de l’api. Ce format n’est plus pris en charge et sera déconseillé à l’avenir.

    Activation et désactivation du service Événements planifiés

    Le service Événements planifiés est activé pour votre service la première fois que vous faites une requête d’événements. Attendez-vous à ce que la réponse à votre première demande ait un retard pouvant atteindre deux minutes.

    Le service Événements planifiés est désactivé pour votre service, s’il ne fait aucune requête pendant 24 heures.

    Maintenance lancée par l’utilisateur

    La maintenance de machine virtuelle lancée par l’utilisateur via le portail Azure, l’API, l’interface de ligne de commande ou PowerShell entraîne un événement planifié. Cela vous permet de tester la logique de préparation de la maintenance dans votre application et à cette dernière de se préparer à la maintenance lancée par l’utilisateur.

    Si vous redémarrez une machine virtuelle, un événement de type Reboot est planifié. Si vous redéployez une machine virtuelle, un événement de type Redeploy est planifié. En règle générale, les événements avec une source d’événement utilisateur peuvent être immédiatement approuvés pour éviter un retard sur les actions lancées par l’utilisateur.

    Utilisation de l’API

    headers

    Quand vous interrogez le service de métadonnées, vous devez fournir l’en-tête Metadata:true pour garantir que la requête n’a pas été redirigée involontairement. L’en-tête Metadata:true est obligatoire pour toutes les requêtes d’événements planifiés. L’absence d’en-tête dans la requête génère une réponse « Requête incorrecte » du service de métadonnées.

    Rechercher des événements

    Vous pouvez rechercher des événements planifiés en effectuant l’appel suivant :

    Exemple Bash

    curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
    

    Exemple de code PowerShell

    Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -Uri "http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01" | ConvertTo-Json -Depth 64
    

    Exemple de code Python

    import json
    import requests
    
    metadata_url ="http://169.254.169.254/metadata/scheduledevents"
    header = {'Metadata' : 'true'}
    query_params = {'api-version':'2020-07-01'}
    
    def get_scheduled_events():           
        resp = requests.get(metadata_url, headers = header, params = query_params)
        data = resp.json()
        return data
    
    

    Une réponse contient un tableau d’événements planifiés. Un tableau vide signifie qu’il n’y a actuellement aucun événement planifié. S’il existe des événements planifiés, la réponse contient un tableau d’événements.

    {
        "DocumentIncarnation": {IncarnationID},
        "Events": [
            {
                "EventId": {eventID},
                "EventType": "Reboot" | "Redeploy" | "Freeze" | "Preempt" | "Terminate",
                "ResourceType": "VirtualMachine",
                "Resources": [{resourceName}],
                "EventStatus": "Scheduled" | "Started",
                "NotBefore": {timeInUTC},       
                "Description": {eventDescription},
                "EventSource" : "Platform" | "User",
                "DurationInSeconds" : {timeInSeconds},
            }
        ]
    }
    

    Propriétés d’événement

    Propriété Description
    Document Incarnation Entier qui augmente lorsque le tableau d’événements change. Les documents avec la même incarnation contiennent les mêmes informations d’événement, et l’incarnation sera incrémentée lorsqu’un événement change.
    EventId GUID pour cet événement.

    Exemple :
    • 602d9444-d2cd-49c7-8624-8643e7171297
    Type d’événement Impact provoqué par cet événement.

    Valeurs :
    • Freeze: une pause de quelques secondes est planifiée pour la machine virtuelle. L’UC et la connectivité réseau peuvent être suspendus, mais cela n’a aucun impact sur la mémoire ni sur les fichiers ouverts.
    • Reboot: un redémarrage est planifié pour la machine virtuelle (la mémoire non persistante est effacée).
    • Redeploy: un déplacement vers un autre nœud est planifié pour la machine virtuelle (le contenu des disques éphémères est perdu).
    • Preempt: la machine virtuelle Spot est supprimée (le contenu des disques éphémères est perdu). Cet événement est mis à disposition dans la mesure du possible
    • Terminate: La suppression de la machine virtuelle est planifiée.
    ResourceType Type de ressource affecté par cet événement.

    Valeurs :
    • VirtualMachine
    Ressources Liste de ressources affectée par cet événement.

    Exemple :
    • ["FrontEnd_IN_0", "BackEnd_IN_0"]
    EventStatus État de cet événement.

    Valeurs :
    • Scheduled: cet événement est planifié pour démarrer après l’heure spécifiée dans la propriété NotBefore.
    • Started: cet événement a démarré.
    Aucun état Completed ou similaire n’est fourni. L’événement n’est plus renvoyé lorsqu’il est terminé.
    NotBefore Heure après laquelle cet événement peut démarrer. Il est garanti que l'événement ne commencera pas avant cette heure. Est vide si l’événement a déjà démarré

    Exemple :
    • Lundi 19 septembre 2016 18:29:47 GMT
    Description Description de cet événement.

    Exemple :
    • Le serveur hôte est en cours de maintenance.
    EventSource Initiateur de l’événement.

    Exemple :
    • Platform: Cet événement est déclenché par la plateforme.
    • User: Cet événement est déclenché par l’utilisateur.
    DurationInSeconds Durée attendue de l’interruption causée par l’événement.

    Exemple :
    • 9 : l’interruption provoquée par l’événement durera 9 secondes.
    • -1 : valeur par défaut utilisée si la durée d’impact est inconnue ou non applicable.

    Planification d’événement

    Chaque événement est planifié à un moment donné dans le futur (délai minimum), en fonction de son type. Cette heure est reflétée dans la propriété NotBefore d’un événement.

    Type d’événement Préavis minimal
    Freeze 15 minutes
    Reboot 15 minutes
    Redeploy 10 minutes
    Preempt 30 secondes
    Terminate Configurable par l’utilisateur : 5 à 15 minutes

    Notes

    Dans certains cas, Azure est en mesure de prédire une défaillance de l’hôte en raison d’un matériel détérioré, et tente d’atténuer l’interruption du service en planifiant une migration. Les machines virtuelles affectées recevront un événement planifié avec une valeur de temps NotBefore généralement définie sur quelques jours dans le futur. La valeur de temps réelle varie en fonction de l’évaluation du risque de la défaillance prédite. Autant que possible, Azure tente de donner un préavis de 7 jours, mais le temps réel varie et peut être inférieur si la prédiction indique qu’il y a de fortes chances que la défaillance du matériel soit imminente. Pour minimiser les risques auxquels votre service serait exposé en cas de défaillance du matériel avant la migration lancée par le système, nous vous recommandons d’auto-redéployer votre machine virtuelle dès que possible.

    Notes

    Dans le cas où le nœud hôte rencontre une défaillance matérielle, Azure contourne la période minimale d’avis, et commence immédiatement le processus de récupération pour les machines virtuelles affectées. Cela réduit le temps de récupération dans le cas où les machines virtuelles affectées ne peuvent pas répondre. Pendant le processus de récupération, un événement est créé pour toutes les machines virtuelles concernées avec EventType = Reboot et EventStatus = Started.

    Fréquence d’interrogation

    Vous pouvez rechercher des mises à jour sur le point de terminaison à la fréquence de votre choix. Toutefois, plus l’intervalle entre deux requêtes est long, plus vous perdez potentiellement du temps pour réagir à un événement à venir. La plupart des événements préviennent de 5 à 15 minutes à l’avance, bien que dans certains cas, 30 secondes suffisent. Pour être sûr de disposer du maximum de temps pour prendre des mesures d’atténuation, nous vous recommandons d’interroger le service une fois pas seconde.

    Démarrer un événement

    Une fois que vous avez pris connaissance d’un événement à venir et que vous avez mis en place une logique d’arrêt appropriée, vous pouvez approuver l’événement en suspens en effectuant un appel POST au service de métadonnées avec EventId. Cet appel indique à Azure qu’il peut raccourcir l’heure de notification minimale (quand c’est possible). L’événement peut ne pas démarrer immédiatement lors de l’approbation. Dans certains cas, Azure nécessitera l’approbation de toutes les machines virtuelles hébergées sur le nœud avant de poursuivre l’événement.

    Voici un exemple de code JSON attendu dans le corps de la requête POST. La requête doit contenir une liste de StartRequests. Chaque StartRequest contient le paramètre EventId correspondant à l’événement que vous souhaitez envoyer :

    {
    	"StartRequests" : [
    		{
    			"EventId": {EventId}
    		}
    	]
    }
    

    Le service retourne toujours un code de réussite 200 dans le cas d’un ID d’événement valide, même s’il a déjà été approuvé par une autre machine virtuelle. Un code d’erreur 400 indique que l’en-tête de requête ou la charge utile a été malformé.

    Exemple Bash

    curl -H Metadata:true -X POST -d '{"StartRequests": [{"EventId": "f020ba2e-3bc0-4c40-a10b-86575a9eabd5"}]}' http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
    

    Exemple de code PowerShell

    Invoke-RestMethod -Headers @{"Metadata" = "true"} -Method POST -body '{"StartRequests": [{"EventId": "5DD55B64-45AD-49D3-BBC9-F57D4EA97BD7"}]}' -Uri http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01 | ConvertTo-Json -Depth 64
    

    Exemple de code Python

    import json
    import requests
    
    def confirm_scheduled_event(event_id):  
       # This payload confirms a single event with id event_id
       payload = json.dumps({"StartRequests": [{"EventId": event_id }]})
       response = requests.post("http://169.254.169.254/metadata/scheduledevents", 
                                headers =  {'Metadata' : 'true'}, 
                                params = {'api-version':'2020-07-01'}, 
                                data = payload)    
       return response.status_code
    

    Notes

    Le fait d’accuser réception d’un événement lui permet de poursuivre pour tous les éléments Resources qu’il contient, et pas seulement pour la machine virtuelle qui en accuse réception. Vous pouvez donc choisir de désigner une amorce de début pour coordonner l’accusé de réception, qui peut être simplement la première machine du champ Resources.

    Exemples de réponses

    Voici un exemple d’une série d’événements qui ont été vus par deux machines virtuelles qui ont été migrées en direct vers un autre nœud.

    La DocumentIncarnation change à chaque fois qu’il y a de nouvelles informations dans Events. Une approbation de l’événement permettrait au gel de se poursuivre à la fois pour WestNO_0 et WestNO_1. La valeur DurationInSeconds de -1 indique que la plateforme ne sait pas combien de temps l’opération prendra.

    {
        "DocumentIncarnation":  1,
        "Events":  [
                   ]
    }
    
    {
        "DocumentIncarnation":  2,
        "Events":  [
                       {
                           "EventId":  "C7061BAC-AFDC-4513-B24B-AA5F13A16123",
                           "EventStatus":  "Scheduled",
                           "EventType":  "Freeze",
                           "ResourceType":  "VirtualMachine",
                           "Resources":  [
                                             "WestNO_0",
                                             "WestNO_1"
                                         ],
                           "NotBefore":  "Mon, 11 Apr 2022 22:26:58 GMT",
                           "Description":  "Virtual machine is being paused because of a memory-preserving Live Migration operation.",
                           "EventSource":  "Platform",
                           "DurationInSeconds":  -1
                       }
                   ]
    }
    
    {
        "DocumentIncarnation":  3,
        "Events":  [
                       {
                           "EventId":  "C7061BAC-AFDC-4513-B24B-AA5F13A16123",
                           "EventStatus":  "Started",
                           "EventType":  "Freeze",
                           "ResourceType":  "VirtualMachine",
                           "Resources":  [
                                             "WestNO_0",
                                             "WestNO_1"
                                         ],
                           "NotBefore":  "",
                           "Description":  "Virtual machine is being paused because of a memory-preserving Live Migration operation.",
                           "EventSource":  "Platform",
                           "DurationInSeconds":  -1
                       }
                   ]
    }
    
    {
        "DocumentIncarnation":  4,
        "Events":  [
                   ]
    }
    
    

    Exemple de code Python

    L’exemple suivant interroge le service de métadonnées pour obtenir les événements planifiés et approuve chaque événement en suspens :

    #!/usr/bin/python
    import json
    import requests
    from time import sleep
    
    # The URL to access the metadata service
    metadata_url ="http://169.254.169.254/metadata/scheduledevents"
    # This must be sent otherwise the request will be ignored
    header = {'Metadata' : 'true'}
    # Current version of the API
    query_params = {'api-version':'2020-07-01'}
    
    def get_scheduled_events():           
        resp = requests.get(metadata_url, headers = header, params = query_params)
        data = resp.json()
        return data
    
    def confirm_scheduled_event(event_id):  
        # This payload confirms a single event with id event_id
        # You can confirm multiple events in a single request if needed      
        payload = json.dumps({"StartRequests": [{"EventId": event_id }]})
        response = requests.post(metadata_url, 
                                headers= header,
                                params = query_params, 
                                data = payload)    
        return response.status_code
    
    def log(event): 
        # This is an optional placeholder for logging events to your system 
        print(event["Description"])
        return
    
    def advanced_sample(last_document_incarnation): 
        # Poll every second to see if there are new scheduled events to process
        # Since some events may have necessarily short warning periods, it is 
        # recommended to poll frequently
        found_document_incarnation = last_document_incarnation
        while (last_document_incarnation == found_document_incarnation):
            sleep(1)
            payload = get_scheduled_events()    
            found_document_incarnation = payload["DocumentIncarnation"]        
            
        # We recommend processing all events in a document together, 
        # even if you won't be actioning on them right away
        for event in payload["Events"]:
    
            # Events that have already started, logged for tracking
            if (event["EventStatus"] == "Started"):
                log(event)
                
            # Approve all user initiated events. These are typically created by an 
            # administrator and approving them immediately can help to avoid delays 
            # in admin actions
            elif (event["EventSource"] == "User"):
                confirm_scheduled_event(event["EventId"])            
                
            # For this application, freeze events less that 9 seconds are considered
            # no impact. This will immediately approve them
            elif (event["EventType"] == "Freeze" and 
                int(event["DurationInSeconds"]) >= 0  and 
                int(event["DurationInSeconds"]) < 9):
                confirm_scheduled_event(event["EventId"])
                
            # Events that may be impactful (eg. Reboot or redeploy) may need custom 
            # handling for your application
            else: 
                #TODO Custom handling for impactful events
                log(event)
        print("Processed events from document: " + str(found_document_incarnation))
        return found_document_incarnation
    
    def main():
        # This will track the last set of events seen 
        last_document_incarnation = "-1"
    
        input_text = "\
            Press 1 to poll for new events \n\
            Press 2 to exit \n "
        program_exit = False 
    
        while program_exit == False:
            user_input = input(input_text)    
            if (user_input == "1"):                        
                last_document_incarnation = advanced_sample(last_document_incarnation)
            elif (user_input == "2"):
                program_exit = True       
    
    if __name__ == '__main__':
        main()
    

    Étapes suivantes