Servizio metadati di Azure: Eventi pianificati per macchine virtuali Windows
Si applica a: ✔️ macchine virtuali di Windows ✔️ set di scalabilità flessibili ✔️ set di scalabilità uniformi
Gli eventi pianificati sono un servizio metadati di Azure che concede all'applicazione il tempo di prepararsi alla manutenzione delle macchine virtuali. Questo servizio secondario offre informazioni sugli eventi di manutenzione imminenti (ad esempio il riavvio), in modo che l'applicazione possa prepararsi di conseguenza e limitare le interruzioni. È disponibile per tutti i tipi di macchine virtuali di Azure, incluse quelle di tipo PaaS e IaaS sia Windows che Linux.
Per informazioni su Eventi pianificati in Linux, vedere Eventi pianificati per macchine virtuali Linux.
Gli eventi pianificati forniscono notifiche proattive sugli eventi imminenti, per informazioni reattive sugli eventi già verificati, vedere informazioni sulla disponibilità delle macchine virtuali in Azure Resource Graph e Creare una regola di avviso di disponibilità per la macchina virtuale di Azure.
Nota
Gli eventi pianificati sono disponibili a livello generale in tutte le aree di Azure. Per informazioni sulla versione più recente, vedere Versione e disponibilità in base all'area geografica.
Perché usare gli eventi pianificati
Per molte applicazioni è un vantaggio avere tempo per prepararsi alla manutenzione delle macchine virtuali. Questo tempo può essere impiegato in attività specifiche dell'applicazione per ottenere un miglioramento in termini di disponibilità, affidabilità e gestibilità, ad esempio:
- Checkpoint e ripristino
- Esaurimento delle connessioni
- Failover della replica primaria
- Rimozione da un pool di bilanciamento del carico
- Registrazione eventi
- Arresto normale
Grazie agli eventi pianificati, l'applicazione è in grado di sapere quando verrà eseguita la manutenzione e di attivare attività specifiche per limitarne l'impatto.
Gli eventi pianificati informano sugli eventi nei casi d'uso seguenti:
- Manutenzione avviata dalla piattaforma (ad esempio, riavvio di macchine virtuali, migrazione in tempo reale o aggiornamenti con manutenzione della memoria per l'host).
- Macchina virtuale in esecuzione in hardware host danneggiato ed è possibile un guasto imminente.
- La macchina virtuale era in esecuzione in un host che ha subito un errore hardware.
- Manutenzione avviata dall'utente, ad esempio il riavvio o la ridistribuzione di una macchina virtuale eseguita dall'utente.
- Eliminazione di istanze di macchina virtuale Spot e set di scalabilità Spot.
Nozioni di base
Il servizio metadati presenta informazioni sulle macchine virtuali in esecuzione usando un endpoint REST accessibile dall'interno della macchina virtuale. Le informazioni sono disponibili tramite un indirizzo IP non instradabile e non sono esposte all'esterno della macchina virtuale.
Ambito
Gli eventi pianificati vengono recapitati e possono essere riconosciuti da:
- Macchine virtuali autonome.
- Tutte le macchine virtuali in un servizio cloud di Azure (versione classica).
- Tutte le macchine virtuali in un set di disponibilità.
- Tutte le macchine virtuali in un gruppo di posizionamento di un set di scalabilità.
Gli eventi pianificati per tutte le macchine virtuali in un intero set di disponibilità o in un gruppo di posizionamento per un set di scalabilità di macchine virtuali vengono recapitati a tutte le altre macchine virtuali nello stesso gruppo o set indipendentemente dall'utilizzo della zona di disponibilità.
Di conseguenza, è opportuno controllare il campo Resources dell'evento per identificare quali macchine virtuali sono interessate.
Nota
Le macchine virtuali con accelerazione delle GPU in un set di scalabilità che usa 1 dominio di errore (FD = 1) riceveranno solo eventi pianificati per la risorsa interessata. Gli eventi non verranno trasmessi a tutte le macchine virtuali nello stesso gruppo di posizionamento.
Individuazione degli endpoint
Per le macchine virtuali abilitate per le reti virtuali, il servizio metadati è disponibile da un indirizzo IP statico non instradabile, 169.254.169.254. L'endpoint completo per la versione più recente degli eventi pianificati è:
http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
Se la macchina virtuale non viene creata all'interno di una rete virtuale, caso predefinito per i servizi cloud e le macchine virtuali classiche, è necessaria logica aggiuntiva per individuare l'indirizzo IP da usare. Per informazioni su come individuare l'endpoint dell'host, vedere l'esempio seguente.
Versione e disponibilità in base all'area geografica
Il servizio eventi pianificati è un servizio con versione. Le versioni sono obbligatorie; la versione corrente è 2020-07-01.
| Versione | Tipo di versione | Aree | Note sulla versione |
|---|---|---|---|
| 01-07-2020 | Disponibilità generale | Tutte le date | |
| 2019-08-01 | Disponibilità generale | Tutte le date | |
| 01/04/2019 | Disponibilità generale | Tutte le date | |
| 2019-01-01 | Disponibilità generale | Tutte le date | |
| 2017-11-01 | Disponibilità generale | Tutte le date | |
| 01-08-2017 | Disponibilità generale | Tutte le date | |
| 2017-03-01 | Anteprima | Tutte le date |
Nota
Le precedenti versioni di anteprima del servizio eventi pianificati supportano {latest} come api-version. Questo formato non è più supportato e verrà rimosso in futuro.
Abilitazione e disabilitazione degli eventi pianificati
Gli eventi pianificati vengono abilitati per il servizio la prima volta che si effettua una richiesta di eventi. Ci si dovrebbe aspettare una risposta con un ritardo di un massimo di due minuti nella prima chiamata e si inizierà a ricevere eventi entro 5 minuti. Gli eventi pianificati sono disabilitati per il servizio se non effettua una richiesta all'endpoint per 24 ore.
Manutenzione avviata dall'utente
La manutenzione delle macchine virtuali avviata dall'utente tramite il portale, l'API o l'interfaccia della riga di comando di Azure oppure tramite PowerShell restituisce un evento pianificato. È quindi possibile testare la logica di preparazione della manutenzione dell'applicazione e permettere all'applicazione di prepararsi per la manutenzione avviata dall'utente.
Se si riavvia una macchina virtuale, viene pianificato un evento di tipo Reboot. Se si ridistribuisce una macchina virtuale, viene pianificato un evento di tipo Redeploy. In genere, gli eventi con un'origine evento utente possono essere approvati immediatamente per evitare un ritardo nelle azioni avviate dall'utente. È consigliabile che una macchina virtuale primaria e secondaria comunichi e approvi gli eventi pianificati generati dall'utente nel caso in cui la macchina virtuale primaria non risponda. L'approvazione immediata degli eventi impedisce ritardi nel ripristino dell'applicazione a uno stato corretto.
Gli eventi pianificati per aggiornamenti del sistema operativo guest del set di scalabilità di macchine virtuali o di nuova creazione delle immagini sono supportati per le dimensioni delle macchine virtuali per utilizzo generico che supportano solo gli aggiornamenti. Non può essere usata con le serie G, M, N e H. Gli eventi pianificati per gli aggiornamenti del sistema operativo guest dei set di scalabilità di macchine virtuali e le ricreazioni dell'immagine sono disabilitati per impostazione predefinita. Per abilitare gli eventi pianificati per queste operazioni sulle dimensioni di macchina virtuale supportate, abilitarle prima di tutto usando OSImageNotificationProfile.
Usare l'API
Panoramica generale
Esistono due componenti principali per la gestione di eventi pianificati, preparazione e ripristino. Tutti gli eventi pianificati correnti che influiscono su una macchina virtuale sono disponibili per la lettura tramite l'endpoint eventi pianificati IMDS. Quando l'evento ha raggiunto uno stato terminale, viene rimosso dall'elenco di eventi. Il diagramma seguente illustra le varie transizioni di stato che un singolo evento pianificato può sperimentare:
Per gli eventi nello stato EventStatus: "Scheduled", è necessario eseguire i passaggi per preparare il carico di lavoro. Al termine della preparazione, è necessario approvare l'evento usando l'API evento pianificata. In caso contrario, l'evento viene approvato automaticamente quando viene raggiunto il tempo NotBefore. Se la macchina virtuale si trova nell'infrastruttura condivisa, il sistema attenderà che anche tutti gli altri tenant nello stesso hardware approvino il processo o il timeout. Dopo aver raccolto le approvazioni da tutte le macchine virtuali interessate o quando il tempo NotBefore viene raggiunto, Azure genera un nuovo payload dell'evento pianificato con EventStatus:"Started" e attiva l'inizio dell'evento di manutenzione. Quando l'evento ha raggiunto uno stato terminale, viene rimosso dall'elenco di eventi. Ciò funge da segnale per il cliente per il ripristino delle macchine virtuali.
Di seguito è riportato lo pseudo codice che illustra un processo per la lettura e la gestione degli eventi pianificati nell'applicazione:
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
Poiché gli eventi pianificati vengono spesso usati per le applicazioni con requisiti di disponibilità elevata, è necessario considerare alcuni casi eccezionali:
- Una volta completato e rimosso un evento pianificato dalla matrice, non ci saranno altri impatti senza un nuovo evento incluso un altro evento EventStatus:"Scheduled"
- Azure monitora le operazioni di manutenzione nell'intera flotta e in rari casi determina che un'operazione di manutenzione è troppo rischiosa da applicare. In tal caso, l'evento pianificato passa direttamente da essere "Programmato" a essere rimosso dalla matrice di eventi
- In caso di errore hardware, Azure ignora lo stato "Scheduled" e passa immediatamente allo stato EventStatus:"Started".
- Anche se l'evento è ancora in stato EventStatus:"Started", potrebbe verificarsi un altro impatto di una durata più breve rispetto a quella pubblicizzata nell'evento pianificato.
Come parte della garanzia di disponibilità di Azure, le macchine virtuali in domini di errore diversi non saranno interessate contemporaneamente dalle operazioni di manutenzione di routine. Tuttavia, possono avere operazioni serializzate una dopo l'altra. Le macchine virtuali in un dominio di errore possono ricevere eventi pianificati con EventStatus:"Scheduled" poco dopo il completamento della manutenzione di un altro dominio di errore. Indipendentemente dall'architettura scelta, mantenere sempre il controllo dei nuovi eventi in sospeso rispetto alle macchine virtuali.
Anche se i tempi esatti degli eventi variano, il diagramma seguente fornisce una linea guida approssimativa per il funzionamento tipico di un'operazione di manutenzione:
- Da EventStatus:"Scheduled" ad Approval Timeout: 15 minuti
- Durata impatto: 7 secondi
- Da EventStatus:"Started" a Completed (evento rimosso dalla matrice eventi): 10 minuti
Tutte le operazioni che influiscono sulla disponibilità delle macchine virtuali genereranno un evento pianificato, ma non tutti gli eventi pianificati verranno visualizzati in altre aree di Azure, ad esempio i log attività di Azure o Integrità risorse. Il controllo regolare degli eventi pianificati garantisce di avere le informazioni più aggiornate su eventuali impatti imminenti sulle macchine virtuali.
Intestazioni
Quando si eseguono query sul servizio metadati, è necessario specificare l'intestazione Metadata:true per garantire che la richiesta non sia stata reindirizzata accidentalmente. L'intestazione Metadata:true è obbligatoria per tutte le richieste di eventi pianificati. Se non si include l'intestazione nella richiesta, il servizio metadati restituisce una risposta di richiesta non valida.
Query per gli eventi
È possibile eseguire query per eventi pianificati eseguendo la chiamata seguente:
Esempio Bash
curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
Esempio 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
Esempio in 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
Una risposta contiene una serie di eventi pianificati. Una matrice vuota indica che al momento non sono presenti eventi pianificati. Nel caso in cui siano presenti eventi pianificati, la risposta contiene una matrice di eventi.
{
"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},
}
]
}
Proprietà dell'evento
| Proprietà | Descrizione |
|---|---|
| Incarnazione documento | Intero che aumenta quando cambia la matrice di eventi. I documenti con la stessa incarnazione contengono le stesse informazioni sugli eventi e l'incarnazione verrà incrementata quando un evento cambia. |
| EventId | Identificatore globalmente univoco per l'evento. Esempio:
|
| EventType | Effetti previsti che questo evento causerà. Valori:
|
| ResourceType | Tipo di risorsa interessata dall'evento. Valori:
|
| Risorse | Elenco di risorse interessate dall'evento. Esempio:
|
| EventStatus | Stato dell'evento. Valori:
Completed o simile non viene mai restituito. Al termine dell'evento, quest'ultimo non viene più restituito. |
| NotBefore | Tempo al termine del quale l'evento può essere avviato. L'evento non viene avviato prima di questa volta. Se l'evento è già stato avviato, l'evento sarà vuoto Esempio:
|
| Descrizione | Descrizione di questo evento. Esempio:
|
| EventSource | Iniziatore dell'evento. Esempio:
|
| DurationInSeconds | Durata prevista dell'interruzione causata dall'evento. Può verificarsi un effetto secondario di una durata più breve durante la finestra di impatto. Esempio:
|
Pianificazione degli eventi
Ogni evento è pianificato con un ritardo minimo che dipende dal tipo di evento. Questo tempo si riflette in una proprietà NotBefore dell'evento.
| EventType | Preavviso minimo |
|---|---|
| Blocca | 15 minuti |
| Riavvio | 15 minuti |
| Ripetere la distribuzione | 10 minuti |
| Termina | Configurabile dall'utente: da 5 a 15 minuti |
Ciò significa che è possibile rilevare una pianificazione futura dell'evento almeno in base al tempo minimo di preavviso prima che si verifichi l'evento. Una volta pianificato un evento, passerà allo stato Started dopo l'approvazione o quando il tempo NotBefore è trascorso. Tuttavia, in rari casi, l'operazione verrà annullata da Azure prima dell'avvio. In tal caso, l'evento verrà rimosso dalla matrice Eventi e l'impatto non si verificherà come pianificato in precedenza.
Nota
In alcuni casi, Azure è in grado di stimare gli errori dell'host dovuti ad hardware danneggiato e tenterà di attenuare le interruzioni del servizio tramite la pianificazione di una migrazione. Le macchine virtuali interessate riceveranno un evento pianificato con un elemento NotBefore che in genere equivale a pochi giorni in futuro. Il tempo effettivo varia a seconda della valutazione del rischio di errore stimato. Quando possibile, Azure prova a fornire un preavviso di 7 giorni, ma il tempo effettivo varia e potrebbe essere inferiore se la stima indica che potrebbe verificarsi un problema di hardware imminente. Per ridurre al minimo i rischi per il servizio qualora l'hardware presenti un guasto prima della migrazione avviata dal sistema, è consigliabile eseguire la ridistribuzione automatica della macchina virtuale appena possibile.
Nota
Nel caso in cui il nodo host subisca un errore hardware, Azure ignora il periodo di preavviso minimo e inizia immediatamente il processo di ripristino per le macchine virtuali interessate. In questo modo si riduce il tempo di ripristino nel caso in cui le macchine virtuali interessate non siano in grado di rispondere. Durante il processo di ripristino verrà creato un evento per tutte le macchine virtuali interessate con EventType = Reboot e EventStatus = Started.
Frequenza di polling
È possibile eseguire il polling dell'endpoint per gli aggiornamenti con frequenza o raramente desiderato. Tuttavia, più tempo intercorre tra le richieste, maggiore è il tempo che si può perdere per reagire a un evento imminente. La maggior parte degli eventi ha da 5 a 15 minuti di preavviso, anche se in alcuni casi l'avviso anticipato potrebbe essere minimo di 30 secondi. Per assicurarsi di avere il più tempo possibile per eseguire azioni di mitigazione, è consigliabile eseguire il polling del servizio una volta al secondo.
Avviare un evento
Dopo aver ricevuto l'avviso di un evento imminente e aver completato la logica per l'arresto normale, è possibile approvare l'evento in sospeso eseguendo una chiamata POST al servizio metadati con EventId. Questa chiamata segnala ad Azure che è possibile ridurre il tempo minimo di notifica, quando possibile. L'evento potrebbe non iniziare immediatamente dopo l'approvazione; in alcuni casi, Azure richiede l'approvazione di tutte le macchine virtuali ospitate nel nodo prima di procedere con l'evento.
Di seguito è riportato l'esempio JSON con il codice previsto nel corpo della richiesta POST. La richiesta deve contenere un elenco di StartRequests. Ogni StartRequest contiene EventId per l'evento che si vuole velocizzare:
{
"StartRequests" : [
{
"EventId": {EventId}
}
]
}
Il servizio restituisce sempre un codice di operazione riuscita 200 se viene passato un ID evento valido, anche se un'altra macchina virtuale ha già approvato l'evento. Un codice di errore 400 indica che l'intestazione o il payload della richiesta non sono validi.
Nota
Gli eventi non procederanno a meno che non siano approvati tramite un messaggio POST o il tempo notBefore trascorso. Sono inclusi gli eventi attivati dall'utente, ad esempio i riavvii delle macchine virtuali dal portale di Azure.
Esempio 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
Esempio 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
Esempio in 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
Nota
Il riconoscimento consente a un evento di procedere per tutti gli elementi Resources dell'evento, non solo per la macchina virtuale che riconosce l'evento. Di conseguenza, è possibile scegliere un coordinatore che si occupi del riconoscimento, che potrebbe essere semplicemente il primo computer elencato nel campo Resources.
Risposte di esempio
Gli eventi seguenti sono un esempio visualizzato da due macchine virtuali di cui è stata eseguita la migrazione in tempo reale a un altro nodo.
DocumentIncarnation cambia ogni volta che sono presenti nuove informazioni in Events. Un'approvazione dell'evento consente al blocco di procedere sia per WestNO_0 che per WestNO_1. DurationInSeconds pari a -1 indica che la piattaforma non conosce il tempo necessario per l'operazione.
{
"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": [
]
}
Esempio Python
L'esempio seguente esegue query sul servizio metadati per gli eventi pianificati e approva ogni evento in sospeso:
#!/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()
Passaggi successivi
- È possibile esaminare gli esempi di codice di Eventi pianificati nel repository GitHub di Eventi pianificati del servizio metadati dell'istanza di Azure.
- Esaminare gli esempi di codice degli eventi pianificati Node.js in repository GitHub degli esempi di Azure.
- Altre informazioni sulle API disponibili nel servizio metadati dell'istanza.
- Informazioni sulla manutenzione pianificata per le macchine virtuali Windows in Azure.
- Informazioni su come monitorare gli eventi pianificati per la macchina virtuale con Log Analytics.
- Informazioni su come registrare gli eventi pianificati usando Hub eventi di Azure nel repository GitHub degli esempi di Azure.