適用於: ✔️ Linux VM ✔️ 彈性擴展集 ✔️ 統一擴展集
排程事件是一項 Azure 中繼資料服務,可讓您的應用程式有時間為虛擬機器 (VM) 維護作準備。 它提供即將進行的維護事件 (例如重新啟動) 相關資訊,讓您的應用程式可預先準備,並將中斷降到最低。 適用於所有 Azure 虛擬機器 類型,包括在 Windows 和 Linux 上的 PaaS 和 IaaS。
如需 Linux 上已排定事件的資訊,請參閱 Linux VM 的已排定事件。
排程事件會主動提供即將發生之事件的通知。 有關過去發生事件的即時資訊,請參閱 Azure Resource Graph 中的 VM 可用性資訊,以及為 Azure 虛擬機器建立可用性警示規則。
注意
已排定事件已在所有 Azure 區域中正式推出。 請參閱版本和區域可用性以取得最新的版本資訊。
為什麼要使用已排定事件?
許多應用程式可受益於 VM 維護的準備時間。 這些時間可用來執行應用程式特定的工作,能改善可用性、可靠性與可維修性,包括:
- 建立檢查點並還原。
- 連線排空。
- 主要複本容錯移轉。
- 從負載平衡器集區移除。
- 事件記錄。
- 優雅關機。
使用已排定事件,應用程式就可以得知維護將於何時進行,並觸發任務,以限制其影響。
排程事件會在下列使用案例中提供事件:
- 由平台起始的維護 (例如:VM 重新啟動、即時遷移或主機記憶體保留更新)。
- 虛擬機器正在狀態降級且預計很快會故障的主機硬體上執行。
- 虛擬機器在發生硬體故障的主機上執行。
- 使用者啟動的維護 (例如,使用者重新啟動或重新部署 VM)。
- Spot VM 和 Spot 擴展集 實例的驅逐。
- Spot 或 Spot Plus 虛擬機面臨較高驅逐風險的早期警示 Spot Rebalance Preview。
基本知識
中繼資料服務會透過可從 VM 內部存取的 REST 端點,公開執行中的 VM 相關資訊。 這項資訊是透過無法路由傳送的 IP 所取得,且不會在 VM 之外公開。
Scope
已排定事件會傳送到下列目標,並由其確認收悉:
- 獨立 虛擬機器。
- Azure 雲端服務 (傳統) 中的所有 VM。
- 可用性設定組中的所有 VM。
- 擴展集放置群組中的所有 VM。
在整個可用性設定組,或虛擬機器擴展集的放置群組中,不論可用性區域的使用方式,所有虛擬機器 (VM) 的已排定事件都會傳送至相同群組或集合中的所有其他 VM。
因此,請檢查事件中的 Resources 欄位以找出哪些 VM 受到影響。
注意
規模設定中的 GPU 加速虛擬機在使用一個容錯網域(FD = 1)時,僅接收與受影響資源相關的排程事件。 事件不會廣播到相同配置組中的所有 VM。
端點發現
針對已啟用 VNET 的 VM,可以從靜態非可路由 IP 169.254.169.254 取得「中繼資料服務」。 最新版已排定事件的完整端點為:
http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
如果未在虛擬網路內建立 VM,雲端服務和傳統 VM 的預設案例,則需要其他邏輯來探索要使用的 IP 位址。 請參閱此範例以了解如何找出主機端點 \(英文\)。
版本和區域可用性
已排定事件服務具有版本。 版本為必填項目;目前的版本是 2020-07-01。
| 版本 | 版本類型 | 地區 | 版本資訊 |
|---|---|---|---|
| 2024-07-09 | 預覽 | 全部 | |
| 2020-07-01 | 正式發行 | 全部 | |
| 2019-08-01 | 正式發行 | 全部 | |
| 2019-04-01 | 正式發行 | 全部 | |
| 2019-01-01 | 正式可用 | 全部 | |
| 2017-11-01 | 正式推出 | 全部 | |
| 2017 年 8 月 1 日 | 正式推出 | 全部 | |
| 2017-03-01 | 預覽 | 全部 |
注意
先前的 Scheduled Events 預覽版本支援 {latest} 作為 API 版本。 此格式將不再受到支援,且未來會被淘汰。
啟用和停用已排定事件
在您第一次提出事件要求時,會為您的服務啟用「已排定事件」。 您應該會在第一次呼叫多達兩分鐘時遇到延遲的回應,而您會在 5 分鐘內開始接收事件。 如果長達 24 小時未向端點提出要求,服務就會停用已排定事件。
使用者啟動的維護
透過 Azure 入口網站、API、CLI 或 PowerShell 發起的使用者 VM 維護作業,會產生排程事件。 這可讓您測試應用程式中的維護準備邏輯,讓應用程式可以為使用者起始的維護預作準備。
如果您重新啟動 VM,則會排定類型為 Reboot 的事件。 如果您重新部署 VM,則會排定類型為 Redeploy 的事件。 一般而言,可以立即核准具有使用者事件來源的事件,以避免延遲使用者起始的動作。 建議以主要與次要 VM 進行通訊,並核准使用者產生的已排定事件,避免主要 VM 沒有回應。 藉由立即核准事件,可防止應用程式恢復到良好狀態時發生延遲。
只有適用於支援記憶體保留更新的一般用途 VM 大小,才支援虛擬機器擴展集 客體 OS 升級或重新安裝映像的已排定事件。 但不適用於 G、M、N 和 H 系列。 根據預設,虛擬機器擴展集 客體 OS 升級或重新安裝映像的已排定事件會處於停用狀態。 若要在支援的 VM 大小上為這些作業啟用已排定事件,請先使用 OSImageNotificationProfile 加以啟用。
使用 API
高階概述
處理已排定事件包含兩個主要元件:準備和復原。 所有影響 VM 的目前已排定事件,都能透過 IMDS 已排定事件端點進行讀取。 當事件達到終端機狀態時,就會從事件清單中移除。 下圖說明了單一已排定事件可能經歷的各種狀態轉換:
針對 EventStatus:“Scheduled” 狀態中的事件,您必須採取步驟來準備工作負載。 準備完成後,應使用已排定事件 API 來核准事件。 否則,一旦到達 NotBefore 時間,即會自動核准事件。 如果 VM 位於共用基礎結構上,系統則會等待相同硬體上的所有其他租用戶也核准作業或逾時。 完成所有受影響 VM 或 NotBefore 時間的核准程序之後,Azure 就會使用 EventStatus: "Started" 產生新的排程事件負載,並觸發維護事件開始。 當事件達到終端機狀態時,就會從事件清單中移除。 這可做為客戶復原其 VM 的訊號。
這段偽程式碼示範了如何在應用程式中讀取及管理排程事件的流程:
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
由於已排定事件通常用於具有高可用性需求的應用程式,因此應考慮一些例外狀況:
- 已排定事件完成並從陣列中移除後,如果沒有新的事件 (包括另一個 EventStatus 為「已啟動」狀態的事件),便不會再產生影響
- Azure 會監視整個機群的維護作業,並在極少數情況下,因認為維護作業的風險太高而判斷無法套用。 在此情況下,排程的事件會直接從「Scheduled」變為從事件陣列中被移除。
- 如果發生硬體故障,Azure 會略過「已排程」狀態,並立即移至 EventStatus:“Started” 狀態。
- 雖然事件仍處於 EventStatus 為「已啟動」的狀態,也可能會因持續時間比已排定事件中公告的還短,而產生其他影響。
不同容錯網域的 VM 不會同時受到例行維護作業的影響,以保障 Azure 的可用性。 然而,作業可一個接一個連續執行。 一個容錯網域中的 VM 可以在另一個容錯網域維護完成後不久,接收 EventStatus:"Scheduled" 的已排定事件。 無論選擇何種結構,請始終檢查 VM 是否有待處理的新事件。
雖然事件發生的確切時間各不相同,但下圖提供了一個大略指引,說明典型維護作業通常如何進行:
- EventStatus:「已排程」到 Approval Timeout: 15 分鐘
- 影響持續時間:7 秒
- 從 EventStatus「已啟動」到「已完成」(事件從事件陣列中移除):10 分鐘
影響 VM 可用性的所有作業都會建立排程的事件,但並非所有排程的事件都會出現在其他 Azure 介面中,例如 Azure 活動記錄或資源健康狀態。 定期檢查已排程的事件,可確保您擁有最 up-to最新的 VM 影響相關信息。
標頭
查詢中繼資料服務時,您必須提供 Metadata:true 標頭,以確保要求未被無意間重新導向。 所有已排程事件的要求都需要 Metadata:true 標頭。 在請求中未包含標頭會導致中繼資料服務回應「Bad Request」。
查詢事件
您只要進行下列呼叫,即可查詢已排定事件:
Bash 範例
curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01
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
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
回應包含排定的事件陣列。 空白陣列表示目前沒有任何排定的事件。 在有排定事件的情況下,回應會包含事件陣列。
{
"DocumentIncarnation": {IncarnationID},
"Events": [
{
"EventId": {eventID},
"EventType": "Reboot" | "Redeploy" | "Freeze" | "Preempt" | "Terminate" | "SpotRebalanceRecommendation",
"ResourceType": "VirtualMachine",
"Resources": [{resourceName}],
"EventStatus": "Scheduled" | "Started" | "Advisory",
"NotBefore": {timeInUTC},
"Description": {eventDescription},
"EventSource" : "Platform" | "User",
"DurationInSeconds" : {timeInSeconds},
}
]
}
事件屬性
| 屬性 | 說明 |
|---|---|
| 文件版本 | 當事件陣列變更時增加的整數。 具有相同化身的檔包含相同的事件資訊,而當事件變更時,化身就會遞增。 |
| EventId | 此事件的全域唯一識別碼。 範例:
|
| 事件類型 | 此事件預期造成的影響。 值:
|
| 資源類型 | 受此事件影響的資源類型。 值:
|
| 資源 | 受此事件影響的資源清單。 範例:
|
| 事件狀態 | 此事件的狀態。 值:
Completed 或類似的狀態。 事件結束後,將不再傳回此事件。 |
| 不早於 | 自此之後可啟動此事件的時間。 事件保證不會在此時間之前啟動。 當事件啟動後,它將會是空白的。 範例:
|
| 說明 | 此事件的描述。 範例:
|
| 事件來源 | 事件啟動器。 範例:
|
| 時間長度(秒) | 事件所造成的中斷預期持續時間。 在影響期間,可能有較短持續時間的次要影響。 範例:
|
事件排定
系統會根據事件類型,為每個事件至少提前一段時間排程。 事件的 NotBefore 屬性會反映這個時間。
| 事件類型 | 最短通知時間 |
|---|---|
| 凍結 | 15 分鐘 |
| 重新啟動 | 15 分鐘 |
| 重新部署 | 10 分鐘 |
| 搶佔 | 30 秒 |
| SpotRebalanceRecommendation | Spot:最長 15 分鐘,Spot Plus:30 秒至 15 分鐘 |
| 終止 | 使用者可設定:5 至 15 分鐘 |
這表示在事件發生前的最短通知時間內,您能夠偵測到事件的未來排程。 事件已排定後,會在通過核准或 NotBefore 時間已過後進入 Started 狀態。 不過,在極少數情況下,Azure 會在作業啟動之前取消作業。 在此情況下,事件會從 Events 陣列中移除,而且不會如先前排程而發生影響。
注意
在某些情況下,Azure 能夠因硬體性能下降而預測主機故障,並嘗試藉由排程遷移來減少對您的服務的中斷。 受影響的虛擬機器會收到含有 NotBefore (通常是未來幾天) 的已排定事件。 實際時間依預測的失敗風險評量而有所不同。 Azure 會儘可能嘗試提供 7 天的提前通知。 實際通知時間會有所不同,如果硬體即將故障的可能性很高,可能會較短。 若要將您服務的風險降至最低,以防萬一硬體在系統起始移轉之前失敗,我們建議您盡快重新部署虛擬機器。
注意
如果主機節點發生硬體故障,Azure 會略過最低通知期間,並立即開始受影響虛擬機的復原程式。 這可減少受影響 VM 無法回應時的復原時間。 在復原過程中,會針對具有 EventType = Reboot 和 EventStatus = Started的所有受影響 VM 建立事件。
輪詢頻率
您可以自行決定輪詢端點更新的頻率。 然而,要求之間的間隔時間越久,您可能會損失更多可用來回應即將發生事件的時間。 大部分事件都有 5 到 15 分鐘的事先通知,但在某些情況下,預先通知可能不到 30 秒。 為確保盡可能有較多時間採取緩和動作,建議您每秒輪詢一次服務。
啟動事件
在您得知即將發生的事件,並完成正常關機邏輯之後,即可使用 POST 向中繼資料服務進行 EventId 呼叫,以核准未處理的事件。 此呼叫向 Azure 表示可縮短最短通知時間 (可能的話)。 事件可能不會在核准時立即啟動。 在某些情況下,Azure 需要核准節點上裝載的所有 VM,然後再繼續進行事件。
以下是 POST 要求內文中預期的 JSON 範例。 請求需包含 StartRequests 清單。 每個 StartRequest 都包含您需要加速之事件的 EventId:
{
"StartRequests" : [
{
"EventId": {EventId}
}
]
}
如果服務傳遞了有效的事件識別碼,則即使另一個 VM 已核准事件,也一律會傳回 200 成功碼。 400 錯誤碼表示要求標頭或酬載的格式錯誤。
注意
事件除非已透過 POST 訊息核准或 NotBefore 時間已過,否則不會繼續。 這包括使用者觸發的事件,例如從 Azure 入口網站重新啟動 VM。
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
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
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
注意
認可事件時,即會讓事件中的所有 Resources 都能繼續進行,而不只是認可該事件的 VM。 因此,您可以挑選一位領導者來協調確認,這可能和Resources欄位中的第一部機器一樣簡單。
範例回應
以下事件是兩台已即時遷移至另一節點的虛擬機所產生的範例。
每當 Events 中有新的資訊時,DocumentIncarnation 就會變動。 事件的核准可讓 WestNO_0 和 WestNO_1 的凍結繼續。
{
"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 2026 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": [
]
}
以下回應顯示一項建議性再平衡:
{
"DocumentIncarnation": 5,
"Events": [
{
"EventId": "{EventId}",
"EventStatus": "Advisory",
"EventType": "SpotRebalanceRecommendation",
"ResourceType": "VirtualMachine",
"Resources": [ "{resourceName}" ],
"NotBefore": "{timeInUTC}",
"Description": "Spot VM is at risk of eviction. Rebalance recommended",
"EventSource": "Platform",
"DurationInSeconds": -1
}
]
}
Python 範例
此範例會查詢元數據服務是否有預定事件,並核准每個待處理的事件。 您可以在 Listener.py 檔案的 vm-scheduled-events-mock-server 存放庫中找到程序代碼。
#!/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 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()
預定事件測試
測試應用程式對排程事件的回應有兩種常見方式:手動觸發使用者發起的事件,或使用模擬伺服器。
您可以透過 Azure 入口網站或 Azure CLI,從 VM 刀鋒視窗中選擇 重新啟動 或 重新部署 虛擬機選項,手動觸發重新部署與重新啟動事件。 此動作會建立一個事件並將其傳送至您的工作負載。
影響多個 VM 的作業,例如主機更新,無法視需要觸發,因此您可以改用模擬伺服器。 vm-scheduled-events-mock-server 提供一個架構,能透過重放實際事件流程來測試應用程式對不同情境的回應,以進行開發和測試。 根據預設,伺服器支援 9 個不同的案例,全都從在 Azure 中執行的 VM 擷取,並代表最常見的案例。 視您的應用程式特定特性而定,這些案例可以擴充為包含更多選項。
下一步
- 在 Azure 執行個體中繼資料已排定事件 GitHub 存放庫 \(英文\) 中檢閱排程的事件程式碼範例。
- 檢閱 Azure 範例 GitHub 存放庫中的 Node.js 已排定事件程式碼範例。
- 深入了解執行個體中繼資料服務中提供的 API。
- 了解 Azure 中 Linux 虛擬機器的計劃性維護。
- 瞭解如何在 Azure Samples GitHub 存放庫中使用 Azure 事件中樞 來記錄已排定事件。
- 使用 vm-scheduled-events-mock-server 來測試應用程式對常見排程事件案例的回應。