Azure Metadata Service: Schemalagda händelser för virtuella Windows-datorer
Gäller för: ✔️ Flexibla skalningsuppsättningar ✔️ för virtuella Windows-datorer ✔️ Enhetliga skalningsuppsättningar
Schemalagda händelser är en Azure Metadata Service som ger ditt program tid att förbereda underhåll av virtuella datorer (VM). Den innehåller information om kommande underhållshändelser (till exempel omstart) så att ditt program kan förbereda sig och begränsa avbrott. Den är tillgänglig för alla typer av Azures virtuella datorer, inklusive PaaS och IaaS på både Windows och Linux.
Information om schemalagda händelser i Linux finns i Schemalagda händelser för virtuella Linux-datorer.
Schemalagda händelser ger proaktiva meddelanden om kommande händelser, för reaktiv information om händelser som redan har inträffat, se information om VM-tillgänglighet i Azure Resource Graph och Skapa tillgänglighetsaviseringsregel för virtuella Azure-datorer.
Kommentar
Schemalagda händelser är allmänt tillgängliga i alla Azure-regioner. Information om den senaste versionen finns i Tillgänglighet för version och region.
Varför ska du använda schemalagda händelser?
Många program kan dra nytta av tiden att förbereda sig inför underhåll av virtuella datorer. Tiden kan användas för att utföra programspecifika uppgifter som förbättrar tillgänglighet, tillförlitlighet och användbarhet, till exempel:
- Kontrollpunkt och återställning.
- Anslutningstömning.
- Primär replikeringsredundans.
- Borttagning från en lastbalanseringspool.
- Händelseloggning.
- Korrekt avstängning.
Med schemalagda händelser kan ditt program identifiera när underhåll ska ske och utföra uppgifter för att begränsa dess påverkan.
Schemalagda händelser tillhandahåller händelser i följande användningsfall:
- Plattformsinitierat underhåll (till exempel omstart av virtuell dator, direktmigrering eller minnesbevarande uppdateringar för värden).
- Den virtuella datorn körs på degraderad värdmaskinvara som förväntas misslyckas snart.
- Den virtuella datorn kördes på en värd som drabbats av ett maskinvarufel.
- Användarinitierat underhåll (till exempel en användare startar om eller omdistribuerar en virtuell dator).
- Avlägsning av instanser för VM för oanvänd kapacitet och Skalningsuppsättning för oanvänd kapacitet.
Grunderna
Metadata Service visar information om hur du kör virtuella datorer med hjälp av en REST-slutpunkt som är tillgänglig från den virtuella datorn. Informationen är tillgänglig via en icke-utfällbar IP-adress och exponeras inte utanför den virtuella datorn.
Omfattning
Schemalagda händelser levereras till och kan bekräftas av:
- Fristående virtuella datorer.
- Alla virtuella datorer i en Azure-molntjänst (klassisk).
- Alla virtuella datorer i en tillgänglighetsuppsättning.
- Alla virtuella datorer i en skalningsuppsättningsplaceringsgrupp.
Kommentar
Schemalagda händelser för alla virtuella datorer i en hel tillgänglighetsuppsättning eller en placeringsgrupp för en vm-skalningsuppsättning levereras till alla andra virtuella datorer i samma grupp eller uppsättning oavsett användning i tillgänglighetszonen.
Därför kontrollerar du fältet Resources i händelsen för att identifiera vilka virtuella datorer som påverkas.
Slutpunktsidentifiering
För virtuella VNET-aktiverade virtuella datorer är metadatatjänsten tillgänglig från en statisk ip-adress som inte kan nås, 169.254.169.254. Den fullständiga slutpunkten för den senaste versionen av Schemalagda händelser är:
http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
Om den virtuella datorn inte skapas i ett virtuellt nätverk, standardfallen för molntjänster och klassiska virtuella datorer, krävs ytterligare logik för att identifiera IP-adressen som ska användas. Information om hur du identifierar värdslutpunkten finns i det här exemplet.
Tillgänglighet för version och region
Tjänsten Schemalagda händelser är version. Versioner är obligatoriska. den aktuella versionen är 2020-07-01.
| Version | Versionstyp | Regioner | Viktig information |
|---|---|---|---|
| 2020-07-01 | Allmän tillgänglighet | Alla | |
| 2019-08-01 | Allmän tillgänglighet | Alla | |
| 2019-04-01 | Allmän tillgänglighet | Alla | |
| 2019-01-01 | Allmän tillgänglighet | Alla | |
| 2017-11-01 | Allmän tillgänglighet | Alla | |
| 2017-08-01 | Allmän tillgänglighet | Alla | |
| 2017-03-01 | Förhandsgranska | Alla |
Kommentar
Tidigare förhandsversioner av schemalagda händelser stöds {latest} som api-version. Det här formatet stöds inte längre och kommer att bli inaktuellt i framtiden.
Aktivera och inaktivera schemalagda händelser
Schemalagda händelser aktiveras för din tjänst första gången du begär händelser. Du bör förvänta dig ett fördröjt svar i ditt första samtal på upp till två minuter. Schemalagda händelser inaktiveras för din tjänst om den inte skickar en begäran till slutpunkten på 24 timmar.
Användarinitierat underhåll
Användarinitierat vm-underhåll via Azure-portalen, API, CLI eller PowerShell resulterar i en schemalagd händelse. Sedan kan du testa logiken för förberedelse av underhåll i ditt program och programmet kan förbereda sig för användarinitierat underhåll.
Om du startar om en virtuell dator schemaläggs en händelse med typen Reboot . Om du distribuerar om en virtuell dator schemaläggs en händelse med typen Redeploy . Vanligtvis kan händelser med en användarhändelsekälla godkännas omedelbart för att undvika en fördröjning av användarinitierade åtgärder. Vi rekommenderar att en primär och sekundär virtuell dator kommunicerar och godkänner användargenererade schemalagda händelser om den primära virtuella datorn slutar svara. Omedelbart godkännande av händelser förhindrar fördröjningar i återställningen av programmet till ett bra tillstånd.
Schemalagda händelser för VMSS-gästoperativsystemuppgraderingar eller nyskapningar stöds för allmänna VM-storlekar som endast stöder minnesbevarande uppdateringar . Det fungerar inte för G-, M-, N- och H-serien. Schemalagda händelser för VMSS-gästoperativsystemuppgraderingar och omskapningar inaktiveras som standard. Om du vill aktivera schemalagda händelser för dessa åtgärder på vm-storlekar som stöds aktiverar du dem först med OSImageNotificationProfile.
Använda API:et
Översikt på hög nivå
Det finns två viktiga komponenter för att hantera schemalagda händelser, förberedelse och återställning. Alla aktuella schemalagda händelser som påverkar en virtuell dator är tillgängliga för läsning via slutpunkten för IMDS-schemalagda händelser. När händelsen har nått ett terminaltillstånd tas den bort från listan över händelser. Följande diagram visar de olika tillståndsövergångar som en enda schemalagd händelse kan uppleva:
För händelser i tillståndet EventStatus:"Scheduled" måste du vidta åtgärder för att förbereda arbetsbelastningen. När förberedelsen är klar bör du godkänna händelsen med hjälp av det schemalagda händelse-API:et. Annars godkänns händelsen automatiskt när NotBefore-tiden nås. Om den virtuella datorn finns i delad infrastruktur väntar systemet sedan på att alla andra klienter på samma maskinvara också ska godkänna jobbet eller tidsgränsen. När godkännanden har samlats in från alla berörda virtuella datorer eller notBefore-tiden nås genererar Azure en ny schemalagd händelsenyttolast med EventStatus:"Started" och utlöser starten av underhållshändelsen. När händelsen har nått ett terminaltillstånd tas den bort från listan över händelser. Det fungerar som en signal för kunden att återställa sina virtuella datorer.
Nedan visas psudeo-kod som visar en process för hur du läser och hanterar schemalagda händelser i ditt program:
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
Eftersom schemalagda händelser ofta används för program med höga tillgänglighetskrav finns det några undantagsfall som bör beaktas:
- När en schemalagd händelse har slutförts och tagits bort från matrisen påverkas inte ytterligare utan en ny händelse, inklusive en annan EventStatus:"Scheduled"-händelse
- Azure övervakar underhållsåtgärder i hela flottan och fastställer i sällsynta fall att en underhållsåtgärd är för hög för att kunna tillämpas. I så fall går den schemalagda händelsen direkt från "Schemalagd" till att tas bort från händelsematrisen
- Vid maskinvarufel kringgår Azure tillståndet "Schemalagd" och flyttar omedelbart till tillståndet EventStatus:"Started".
- Även om händelsen fortfarande är i tillståndet EventStatus:"Started" kan det finnas en annan effekt av en kortare varaktighet än vad som annonserades i den schemalagda händelsen.
Som en del av Azures tillgänglighetsgaranti påverkas inte virtuella datorer i olika feldomäner av rutinmässiga underhållsåtgärder samtidigt. De kan dock ha åtgärder serialiserade efter varandra. Virtuella datorer i en feldomän kan ta emot schemalagda händelser med EventStatus:"Scheduled" kort efter att en annan feldomäns underhåll har slutförts. Oavsett vilken arkitektur du har valt fortsätter du alltid att söka efter nya händelser som väntar mot dina virtuella datorer.
Även om de exakta tidpunkterna för händelser varierar, innehåller följande diagram en grov riktlinje för hur en typisk underhållsåtgärd fortsätter:
- EventStatus:"Scheduled" to Approval Timeout: 15 minutes
- Effektvaraktighet: 7 sekunder
- EventStatus:"Started" to Completed (event removed from Events array): 10 minutes
Sidhuvuden
När du frågar metadatatjänsten måste du ange huvudet Metadata:true för att säkerställa att begäran inte omdirigerades oavsiktligt. Huvudet Metadata:true krävs för alla schemalagda händelsebegäranden. Om du inte tar med huvudet i begäran resulterar det i ett "Felaktig begäran"-svar från metadatatjänsten.
Fråga efter händelser
Du kan fråga efter schemalagda händelser genom att göra följande anrop:
Bash-exempel
curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
PowerShell-exempel
Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -Uri "http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01" | ConvertTo-Json -Depth 64
Python-exempel
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
Ett svar innehåller en matris med schemalagda händelser. En tom matris innebär att inga händelser för närvarande är schemalagda. Om det finns schemalagda händelser innehåller svaret en matris med händelser.
{
"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},
}
]
}
Händelseegenskaper
| Property | beskrivning |
|---|---|
| Dokument-inkarnation | Heltal som ökar när händelsematrisen ändras. Dokument med samma inkarnation innehåller samma händelseinformation och inkarnationen ökas när en händelse ändras. |
| EventId | Globalt unik identifierare för den här händelsen. Exempel:
|
| EventType | Förväntad inverkan den här händelsen kommer att orsaka. Värden:
|
| ResourceType | Typ av resurs som händelsen påverkar. Värden:
|
| Resurser | Lista över resurser som händelsen påverkar. Exempel:
|
| EventStatus | Status för den här händelsen. Värden:
Completed eller liknande status har någonsin angetts. Händelsen returneras inte längre när händelsen är klar. |
| NotBefore | Tid efter vilken den här händelsen kan starta. Händelsen kommer garanterat inte att starta före den här tiden. Blir tom om händelsen redan har startats Exempel:
|
| beskrivning | Beskrivning av den här händelsen. Exempel:
|
| EventSource | Initieraren av händelsen. Exempel:
|
| DurationInSeconds | Den förväntade varaktigheten för avbrottet som orsakas av händelsen. Exempel:
|
Schemaläggning av händelser
Varje händelse schemaläggs en minsta tid i framtiden baserat på händelsetypen. Den här tiden återspeglas i en händelses NotBefore egenskap.
| EventType | Minsta meddelande |
|---|---|
| Frys | 15 minuter |
| Starta om | 15 minuter |
| Omdistribuera | 10 minuter |
| Säg upp | Användaren kan konfigureras: 5 till 15 minuter |
Det innebär att du kan identifiera ett framtida schema för händelsen minst med den minsta varseltiden innan händelsen inträffar. När en händelse har schemalagts flyttas den Started till tillståndet när den har godkänts eller tiden NotBefore har passerat. I sällsynta fall avbryts dock åtgärden av Azure innan den startas. I så fall tas händelsen bort från matrisen Händelser och effekten sker inte som tidigare schemalagt.
Kommentar
I vissa fall kan Azure förutsäga värdfel på grund av degraderad maskinvara och försöker minimera störningar i tjänsten genom att schemalägga en migrering. Berörda virtuella datorer får en schemalagd händelse med en NotBefore händelse som vanligtvis är några dagar i framtiden. Den faktiska tiden varierar beroende på den förväntade riskbedömningen av fel. Azure försöker ge 7 dagars förvarning när det är möjligt, men den faktiska tiden varierar och kan vara mindre om förutsägelsen är att det finns en stor chans att maskinvaran misslyckas inom kort. För att minimera risken för din tjänst om maskinvaran misslyckas innan den systeminitierade migreringen rekommenderar vi att du distribuerar om den virtuella datorn så snart som möjligt.
Kommentar
Om värdnoden drabbas av ett maskinvarufel kringgår Azure den minsta uppsägningstiden och påbörjar omedelbart återställningsprocessen för berörda virtuella datorer. Detta minskar återställningstiden om de berörda virtuella datorerna inte kan svara. Under återställningsprocessen skapas en händelse för alla berörda virtuella datorer med EventType = Reboot och EventStatus = Started.
Avsökningsfrekvens
Du kan avsöka slutpunkten efter uppdateringar så ofta eller sällan som du vill. Men ju längre tid mellan begäranden, desto mer tid kan du eventuellt förlora för att reagera på en kommande händelse. De flesta händelser har 5 till 15 minuters förvarning, men i vissa fall kan förvarning vara så lite som 30 sekunder. Vi rekommenderar att du avsöker tjänsten en gång per sekund för att säkerställa att du har så mycket tid som möjligt att vidta åtgärder.
Starta en händelse
När du har lärt dig om en kommande händelse och har slutfört logiken för en korrekt avstängning kan du godkänna den utestående händelsen genom att göra ett POST anrop till Metadata Service med EventId. Det här anropet anger för Azure att det kan förkorta den minsta meddelandetiden (när det är möjligt). Händelsen kanske inte startar omedelbart efter godkännande, i vissa fall kräver Azure godkännande av alla virtuella datorer som finns på noden innan du fortsätter med händelsen.
Följande JSON-exempel förväntas i begärandetexten POST . Begäran bör innehålla en lista med StartRequests. Var och StartRequest en innehåller EventId för den händelse som du vill påskynda:
{
"StartRequests" : [
{
"EventId": {EventId}
}
]
}
Tjänsten returnerar alltid en 200-framgångskod om den skickas ett giltigt händelse-ID, även om en annan virtuell dator redan har godkänt händelsen. En 400-felkod anger att begärandehuvudet eller nyttolasten var felaktigt formaterad.
Kommentar
Händelser fortsätter inte om de inte antingen godkänns via ett POST-meddelande eller NotBefore-tiden förflutit. Detta inkluderar användarutlösta händelser, till exempel omstarter av virtuella datorer från Azure-portalen.
Bash-exempel
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
PowerShell-exempel
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
Python-exempel
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
Kommentar
Genom att bekräfta en händelse kan händelsen fortsätta för alla Resources i händelsen, inte bara den virtuella dator som bekräftar händelsen. Därför kan du välja en ledare för att samordna bekräftelsen, vilket kan vara lika enkelt som den första datorn i fältet Resources .
Exempelsvar
Följande händelser är ett exempel som sågs av två virtuella datorer som direkt migrerades till en annan nod.
DocumentIncarnation Ändras varje gång det finns ny information i Events. Ett godkännande av händelsen skulle göra det möjligt för frysningen att fortsätta för både WestNO_0 och WestNO_1. - DurationInSeconds 1 anger att plattformen inte vet hur lång tid åtgärden tar.
{
"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": [
]
}
Python-exempel
Följande exempel frågar metadatatjänsten efter schemalagda händelser och godkänner varje utestående händelse:
#!/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()
Nästa steg
- Granska kodexemplen schemalagda händelser i GitHub-lagringsplatsen schemalagda händelser för Azure-instansmetadata.
- Granska kodexemplen Node.js Scheduled Events i GitHub-lagringsplatsen Azure Samples.
- Läs mer om de API:er som är tillgängliga i instansmetadatatjänsten.
- Lär dig mer om planerat underhåll för virtuella Windows-datorer i Azure.
- Lär dig hur du övervakar schemalagda händelser för dina virtuella datorer via Log Analytics.
- Lär dig hur du loggar schemalagda händelser med Hjälp av Azure Event Hubs på GitHub-lagringsplatsen Azure Samples.