Служба метаданных Azure: подслужба "Запланированные события" для виртуальных машин Windows

Применимо к: ✔️ Виртуальные машины Windows ✔️ Гибкие масштабируемые наборы ✔️ Универсальные масштабируемые наборы

Запланированные события — это служба метаданных Azure, которая дает время вашему приложению для подготовки к обслуживанию виртуальной машины. Эта служба предоставляет сведения о предстоящем событии обслуживания (например, о перезагрузке), чтобы приложение могло подготовиться к ним и ограничить перебои в работе. Она доступна для всех типов виртуальных машин Azure, включая PaaS и IaaS (как для Windows, так и для Linux).

Сведения о запланированных событиях в Linux см. в статье Служба метаданных Azure. Запланированные события (предварительная версия) для виртуальных машин Linux.

Запланированные события предоставляют упреждающие уведомления о предстоящих событиях для реактивной информации о событиях, которые уже произошли, см . сведения о доступности виртуальных машин в Azure Resource Graph и правиле создания оповещений о доступности для виртуальной машины Azure.

Почему необходимо использовать запланированные события?

Во многих приложениях время на подготовку к обслуживанию виртуальной машины может положительно повлиять на их работу. Его можно использовать для выполнения конкретных задач по повышению доступности, надежности и удобства обслуживания:

• создание контрольных точек и восстановление;
• фильтрация подключений;
• отработка отказа первичной реплики;
• удаление из пула подсистемы балансировки нагрузки;
• ведение журнала событий;
• нормальное завершение работы.

Используя запланированные события, приложение может учесть время, когда будет выполняться техническое обслуживание, и запустить задачи для ограничения его влияния.

Запланированные события предусматривают события в следующих случаях:

• инициированное платформой обслуживание (например, перезагрузка виртуальной машины, динамическая миграция или обновление с сохранением памяти для узла);
• виртуальная машина работает на оборудовании со сниженной производительностью, для которого в ближайшее время прогнозируется сбой;
• виртуальная машина запущена на узле, на котором произошел сбой оборудования;
• обслуживание, инициированное пользователем (например, пользователь перезагружает или повторно развертывает виртуальную машину).
• Вытеснение экземпляров точечных виртуальных машин и точечных масштабируемых наборов.

Основы

Служба метаданных предоставляет сведения о работающих виртуальных машинах с помощью конечной точки REST, которая доступна из виртуальной машины. Сведения доступны через неизменяемый IP-адрес и не предоставляются за пределами виртуальной машины.

Область

Запланированные события доставляются и могут быть подтверждены следующими способами:

• автономным виртуальным машинам;
• Все виртуальные машины в облачной службе Azure (классическая модель).
• всем виртуальным машинам в группе доступности;
• всем виртуальным машинам в группе размещения масштабируемого набора.

Запланированные события для всех виртуальных машин (виртуальных машин) во всей группе доступности или группе размещения для масштабируемого набора виртуальных машин предоставляются всем остальным виртуальным машинам в одной группе или наборе независимо от использования зоны доступности.

Поэтому проверьте поле Resources в событии, чтобы определить, какие виртуальные машины затронуты.

Обнаружение конечной точки

Для виртуальных машин с поддержкой виртуальной сети служба метаданных доступна со статического немаршрутизируемого IP-адреса, 169.254.169.254. Полная конечная точка для последней версии службы "Запланированные события" выглядит так:

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

Если виртуальная машина не создана в виртуальная сеть, варианты по умолчанию для облачных служб и классических виртуальных машин требуют дополнительной логики для обнаружения ИСПОЛЬЗУЕМОго IP-адреса. Чтобы узнать, как выполнить обнаружение конечной точки узла, просмотрите этот пример.

Доступность версий и доступность в регионах

Служба запланированных событий имеет версии. Версии являются обязательными. Сейчас используется версия от 2020-07-01.

Включение и отключение Запланированных событий

Служба "Запланированные события" включается для вашей службы, когда вы впервые запрашиваете события. Вы должны ожидать отложенный ответ в первом вызове до двух минут, и вы начнете получать события в течение 5 минут. Запланированные события отключены для службы, если он не выполняет запрос к конечной точке в течение 24 часов.

Обслуживание, инициированное пользователем

Обслуживание виртуальных машин, инициированное пользователем на портале Azure, в API, Azure CLI или PowerShell, приведет к созданию запланированных событий. Затем можно протестировать логику подготовки обслуживания в вашем приложении, а также его можно подготовить к обслуживанию, инициированному пользователем.

При перезагрузке виртуальной машины событие с типом Reboot добавляется в расписание. При повторном развертывании виртуальной машины событие с типом Redeploy добавляется в расписание. Как правило, события с источником событий пользователя можно немедленно утвердить, чтобы избежать задержки инициированных пользователем действий. Мы советуем взаимодействовать с первичной и вторичной виртуальной машиной и утверждать созданные пользователем запланированные события, если основная виртуальная машина не отвечает. Немедленное утверждение событий предотвращает задержки при восстановлении приложения обратно в хорошее состояние.

Запланированные события для Масштабируемые наборы виртуальных машин обновления гостевой ОС или повторного просмотра поддерживаются для размеров виртуальных машин общего назначения, поддерживающих только сохранение обновлений в памяти. Оно не работает для серий G, M, N и H. Запланированные события для Масштабируемые наборы виртуальных машин обновления гостевой ОС и повторного создания образов по умолчанию отключены. Чтобы включить запланированные события для этих операций с поддерживаемыми размерами виртуальных машин, сначала включите их с помощью OSImageNotificationProfile.

Использование API

Общие сведения о высоком уровне

Существует два основных компонента для обработки запланированных событий, подготовки и восстановления. Все текущие запланированные события, влияющие на виртуальную машину, доступны для чтения через конечную точку запланированных событий IMDS. Когда событие достигло состояния терминала, оно удаляется из списка событий. На следующей схеме показаны различные переходы состояния, которые могут выполняться одним запланированным событием:

Для событий в состоянии EventStatus:"Scheduled" необходимо выполнить действия по подготовке рабочей нагрузки. После завершения подготовки необходимо утвердить событие с помощью API запланированных событий. В противном случае событие автоматически утверждается при достижении времени NotBefore. Если виртуальная машина находится в общей инфраструктуре, система будет ожидать, пока все остальные клиенты на одном оборудовании также утверждают задание или время ожидания. После сбора утверждений со всех затронутых виртуальных машин или времени NotBefore Azure создает новую полезные данные запланированного события с помощью EventStatus:"Started" и запускает начало события обслуживания. Когда событие достигло состояния терминала, оно удаляется из списка событий. Это служит сигналом для клиента для восстановления виртуальных машин.

Ниже приведен код psudeo, демонстрирующий процесс чтения и управления запланированными событиями в приложении:

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

Так как запланированные события часто используются для приложений с высокими требованиями к доступности, существует несколько исключительных случаев, которые следует учитывать:

1. После завершения запланированного события и удаления из массива никаких дополнительных последствий без нового события, включая другое событие EventStatus:"Scheduled"
2. Azure Monitor выполняет операции обслуживания во всем флоте и в редких случаях определяет, что операция обслуживания слишком высока, чтобы применить. В этом случае запланированное событие переходит непосредственно из "Scheduled" для удаления из массива событий
3. В случае сбоя оборудования Azure проходит состояние "Запланировано" и немедленно переходит в состояние EventStatus:"Started".
4. Хотя событие по-прежнему находится в состоянии EventStatus:"Started", может оказаться еще одним воздействием меньшей длительности, чем то, что было объявлено в запланированном событии.

В рамках гарантии доступности Azure виртуальные машины в разных доменах сбоя не будут влиять на обычные операции обслуживания одновременно. Однако они могут иметь сериализованные операции друг за другом. Виртуальные машины в одном домене сбоя могут получать запланированные события с помощью EventStatus:"Scheduled" вскоре после завершения обслуживания другого домена сбоя. Независимо от выбранной архитектуры всегда проверяйте наличие новых событий, ожидающих от виртуальных машин.

Хотя точные сроки событий зависят, на следующей схеме представлено грубое руководство по тому, как выполняется обычная операция обслуживания:

• EventStatus:"Scheduled" to Approval Timeout: 15 минут
• Длительность воздействия: 7 секунд
• EventStatus:"Started" to Completed (событие удалено из массива событий): 10 минут

Все операции, влияющие на доступность виртуальной машины, приводят к запланированному событию, однако не все запланированные события будут отображаться в других поверхностях Azure, таких как журналы действий Azure или Работоспособность ресурсов. Регулярно проверяя запланированные события, вы сможете получить самые актуальные сведения о предстоящих последствиях для виртуальных машин.

Заголовки

При запросе службы метаданных необходимо указать заголовок Metadata:true, чтобы удостовериться, что он не был случайно перенаправлен. Заголовок Metadata:true является обязательным для всех запросов запланированных событий. Невозможность включить заголовок в запрос приведет к ответу службы метаданных "Ошибка запроса".

Запрос сведений о событиях

Чтобы получить сведения о запланированных событиях, выполните следующий вызов.

Пример 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",
            "ResourceType": "VirtualMachine",
            "Resources": [{resourceName}],
            "EventStatus": "Scheduled" | "Started",
            "NotBefore": {timeInUTC},       
            "Description": {eventDescription},
            "EventSource" : "Platform" | "User",
            "DurationInSeconds" : {timeInSeconds},
        }
    ]
}

Свойства событий

Планирование события

В зависимости от типа каждое будущее событие будет выполняться минимальное количество времени. Это время отражается в свойстве события NotBefore.

Это означает, что вы можете определить будущее расписание события по крайней мере по минимальному времени уведомления до возникновения события. После запланированного события он перейдет в Started состояние после его утверждения или NotBefore времени. Однако в редких случаях операция будет отменена Azure перед началом работы. В этом случае событие будет удалено из массива событий, и влияние не будет происходить как ранее запланированное.

Периодичность опроса

Вы можете опрашивать конечную точку на предмет наличия обновлений с любой частотой. Но чем больше время между запросами, тем меньше времени у вас может остаться для реагирования на предстоящее событие. Для большинства событий оповещения отправляются в диапазоне от 5 до 15 минут до начала события, но в некоторых случаях уведомление может поступить всего за 30 секунд. Чтобы обеспечить максимально возможный запас времени для выполнения действий по устранению рисков, мы рекомендуем опрашивать службу каждую секунду.

Запуск события

После того, как вы узнали о предстоящем событии и завершили все действия для корректного завершения работы, вы можете утвердить ожидающее событие, выполнив вызов POST к службе метаданных Azure с помощью EventId. Этот вызов указывает службе Azure, что она может сократить минимальное время уведомления (если возможно). Событие может не начинаться сразу после утверждения, в некоторых случаях Azure требует утверждения всех виртуальных машин, размещенных на узле, прежде чем продолжить работу с событием.

Следующий пример кода JSON ожидается в тексте запроса POST. Запрос должен содержать список StartRequests. Каждый StartRequest содержит EventId для события, которое нужно ускорить:

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

Служба всегда возвращает код успешного выполнения 200, если он передает допустимый идентификатор события, даже если другая виртуальная машина уже одобрила событие. Код ошибки 400 указывает, что заголовок запроса или полезные данные были неправильно сформированы.

Пример 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

Примеры ответов

Ниже приведен пример, который был замечен двумя виртуальными машинами, которые были перенесены в другой узел.

При DocumentIncarnation каждом изменении новых сведений в Eventsней возникают новые сведения. Утверждение события позволит выполнить заморозку как для WestNO_0, так и для WestNO_1. Значение DurationInSeconds -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 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

В следующем примере выполняется запрос запланированных событий в службе метаданных, а затем утверждение каждого ожидающего события.

#!/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()

Следующие шаги

• Просмотрите примеры кода запланированных событий в статье Azure Metadata Service: Scheduled Events Samples (Служба метаданных Azure: примеры запланированных событий).
• Просмотрите примеры кода запланированных событий Node.js в репозитории GitHub с примерами Azure.
• Дополнительные сведения об API, доступных в службе метаданных экземпляра.
• Подробнее о плановом обслуживании виртуальных машин Windows в Azure.
• Узнайте, как отслеживать запланированные события для виртуальных машин с помощью Log Analytics.
• Узнайте, как регистрировать запланированные события с помощью Центры событий Azure в репозитории GitHub azure Samples.