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.
Les événements planifiés fournissent des notifications proactives sur les événements à venir. Pour obtenir des informations réactives sur les événements qui se sont déjà produits, consultez les articles Informations sur la disponibilité des machines virtuelles dans Azure Resource Graph et Créer une règle d’alerte de disponibilité pour une machine virtuelle Azure.
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 :
- Maintenance lancée par la plateforme (par exemple, redémarrage de machine virtuelle, migration dynamique ou mémoire conservant les mises à jour pour l’hôte).
- La machine virtuelle est en cours d’exécution sur le matériel hôte détérioré dont la défaillance prochaine est prédite.
- La machine virtuelle s’est exécutée sur un hôte qui a subi une défaillance matérielle.
- L’utilisateur a lancé une maintenance (par exemple, un utilisateur redémarre ou redéploie une machine virtuelle).
- Évictions d’instances de machine virtuelle Spot et de groupe de machines virtuelles identiques Spot.
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. Les informations sont disponibles via une adresse IP non routable et ne sont pas exposées en dehors de la machine virtuelle.
Étendue
Les événements planifiés sont remis et leur réception peut être confirmée par :
- Machines virtuelles autonomes.
- Toutes les machines virtuelles d’un service cloud Azure (classique).
- Toutes les machines virtuelles d’un groupe à haute disponibilité
- Toutes les machines virtuelles d’un groupe de placement de groupe identique
Les événements planifiés pour toutes les machines virtuelles d'un groupe à haute disponibilité entier ou d'un groupe de sélection élective pour un groupe de machines virtuelles identiques sont transmis à toutes les autres machines virtuelles du même groupe ou ensemble, indépendamment de l'utilisation de la zone de disponibilité.
Par conséquent, vérifiez le champ Resources de l’événement pour identifier les machines virtuelles concernées.
Remarque
Les machines virtuelles accélérées par processeur graphique dans un groupe identique utilisant 1 domaine d’erreur (FD = 1) recevront uniquement les événements planifiés pour la ressource affectée. Les événements ne seront pas diffusés sur toutes les machines virtuelles du même groupe de placement.
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 | |
| 2019-08-01 | Disponibilité générale | Tous | |
| 2019-04-01 | Disponibilité générale | Tous | |
| 2019-01-01 | Disponibilité générale | Tous | |
| 2017-11-01 | Disponibilité générale | Tous | |
| 2017-08-01 | Disponibilité générale | Tous | |
| 2017-03-01 | PRÉVERSION | Tous |
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 à un retard pouvant atteindre deux minutes dans la réponse à votre premier appel. Vous commencerez à recevoir des événements dans les 5 minutes. Le service Événements planifiés est désactivé pour votre service, s’il ne fait aucune requête au point de terminaison 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. Nous vous conseillons d’avoir une machine virtuelle principale et une machine virtuelle secondaire qui communiquent et approuvent les événements planifiés qui sont générés par l’utilisateur au cas où la machine virtuelle principale viendrait à ne plus répondre. L’approbation immédiate des événements évite les retards dans la récupération de votre application à un bon état.
Les événements planifiés pour les mises à niveau ou réinitialisations du système d’exploitation invité Virtual Machine Scale Sets sont pris en charge pour les tailles de machine virtuelle à usage général qui prennent uniquement en charge les mises à jour avec préservation de la mémoire. Elle ne fonctionne pas pour les modèles de série G, M, N et H. Les événements planifiés pour les mises à niveau et réinitialisations du système d’exploitation invité Virtual Machine Scale Sets sont désactivés par défaut. Pour activer les événements planifiés pour ces opérations sur les tailles de machine virtuelle prises en charge, commencez par les activer à l’aide de OSImageNotificationProfile.
Utilisation de l’API
Vue d’ensemble globale
Il existe deux composants principaux pour gérer les événements planifiés: la préparation et la récupération. Tous les événements planifiés actuels ayant un impact sur une machine virtuelle peuvent être lus à partir du point de terminaison IMDS Scheduled Events. Lorsque l’événement atteint un état terminal, il est supprimé de la liste des événements. Le diagramme suivant montre les différentes transitions d’état qu’un seul événement planifié peut subir :
Pour les événements à l’état EventStatus: « Scheduled », vous devez prendre des mesures pour préparer votre charge de travail. Une fois la préparation terminée, vous devez approuver l’événement à l’aide de l’API d’événement planifié. Dans le cas contraire, l'événement est automatiquement approuvé lorsque le délai NotBefore est atteint. Si la machine virtuelle se trouve sur une infrastructure partagée, le système attendra que tous les autres locataires sur le même matériel approuvent également le travail ou le délai d’expiration. Une fois que les approbations sont collectées à partir de toutes les machines virtuelles concernées ou que l’heure NotBefore est atteinte, Azure génère une nouvelle charge utile d’événement planifiée avec EventStatus: « Started » et déclenche le début de l’événement de maintenance. Lorsque l’événement atteint un état terminal, il est supprimé de la liste des événements. Le client reçoit alors le signal de récupérer ses machines virtuelles.
Voici un code pseudo illustrant un processus de lecture et de gestion des événements planifiés dans votre application :
current_list_of_scheduled_events = get_latest_from_se_endpoint()
#prepare for new events
for each event in current_list_of_scheduled_events:
if event not in previous_list_of_scheduled_events:
prepare_for_event(event)
#recover from completed events
for each event in previous_list_of_scheduled_events:
if event not in current_list_of_scheduled_events:
receover_from_event(event)
#prepare for future jobs
previous_list_of_scheduled_events = current_list_of_scheduled_events
Étant donné que les événements planifiés sont souvent utilisés pour les applications avec des exigences de haute disponibilité, quelques cas exceptionnels doivent être pris en compte :
- Une fois qu'un événement planifié est terminé et supprimé du tableau, il n'y aura plus d'impact sans un nouvel événement, notamment un autre événement EventStatus : « Planifié ».
- Azure surveille les opérations de maintenance sur l’ensemble de la flotte et, dans de rares circonstances, détermine qu’une opération de maintenance présente un risque trop élevé pour s’appliquer. Dans ce cas, l'événement planifié passe directement du statut de « planifié » à celui de « supprimé » du tableau des événements.
- En cas de défaillance matérielle, Azure contourne l'état « planifié » et passe immédiatement à l'état EventStatus : « démarré ».
- Alors que l'événement est toujours dans l'état EventStatus : « démarré », il peut y avoir un autre impact d'une durée plus courte que celle annoncée dans l'événement planifié.
Dans le cadre de la garantie de disponibilité d’Azure, les machines virtuelles dans différents domaines d’erreur ne seront pas affectées par les opérations de maintenance de routine en même temps. Toutefois, ils peuvent avoir des opérations sérialisées les unes après les autres. Les machines virtuelles d’un domaine d’erreur peuvent recevoir des événements planifiés avec EventStatus: « Scheduled » peu après la fin de la maintenance d’un autre domaine d’erreur. Quelle que soit l’architecture choisie, vérifiez toujours les nouveaux événements en attente sur vos machines virtuelles.
Bien que le calendrier exact des événements varie, le diagramme suivant fournit une directive approximative pour la façon dont une opération de maintenance classique se déroule :
- EventStatus: « Scheduled » pour délai d’expiration d’approbation : 15 minutes
- Durée de l’impact : 7 secondes
- EventStatus: « Started » à complété (événement supprimé du tableau d’événements) : 10 minutes
En-têtes
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 :
|
| Type d’événement | Impact attendu de cet événement. Valeurs :
|
| ResourceType | Type de ressource affecté par cet événement. Valeurs :
|
| Ressources | Liste de ressources affectée par cet événement. Exemple :
|
| EventStatus | État de cet événement. Valeurs :
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 :
|
| Description | Description de cet événement. Exemple :
|
| EventSource | Initiateur de l’événement. Exemple :
|
| DurationInSeconds | Durée attendue de l’interruption causée par l’événement. Il peut y avoir des impacts secondaires d’une durée plus courte pendant la fenêtre d’impact. Exemple :
|
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 |
| Terminate | Configurable par l’utilisateur : 5 à 15 minutes |
Cela signifie que vous pouvez détecter une planification future d’au moins le temps de préavis minimum avant que l’événement ne se produise. Une fois qu’un événement est planifié, il passe à Started l’état démarré une fois qu’il a été approuvé ou avant NotBefore que le délai ne soit écoulé. Toutefois, dans de rares cas, l’opération est annulée par Azure avant son démarrage. Dans ce cas, l’événement sera supprimé du tableau Événements et l’impact ne se produira pas comme prévu précédemment.
Remarque
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 après approbation. Dans certains cas, Azure requiert 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 s’il reçoit un ID d’événement valide, même si une autre machine virtuelle a déjà approuvé l’événement. Un code d’erreur 400 indique que l’en-tête de requête ou la charge utile a été malformé.
Notes
Les événements ne se déroulent pas, sauf s’ils sont approuvés par le biais d’un message POST ou que la durée NotBefore s’écoule. Cela inclut les événements déclenchés par l’utilisateur, comme les redémarrages de machines virtuelles à partir du Portail Azure.
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
Les événements suivants sont un exemple de ce qu'ont vu 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": 5
}
]
}
{
"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": 5
}
]
}
{
"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 (for example 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
- Passez en revue les exemples de code d’événements planifiés disponibles dans le dépôt GitHub d’événements planifiés de métadonnées d’instance Azure.
- Passez en revue les exemples de code d’événements planifiés Node.js disponibles dans le référentiel Azure Samples GitHub.
- Apprenez-en davantage sur les API disponibles dans le service de métadonnées d’instance.
- Découvrez plus d’informations sur la maintenance planifiée pour les machines virtuelles Windows dans Azure.
- Découvrez comment surveiller les événements planifiés pour vos machines virtuelles via log Analytics.
- Découvrez comment journaliser des événements planifiés à l’aide d’Azure Event Hubs dans le référentiel Azure Samples GitHub.