Azure Metadata Service: Scheduled Events para VMs do Linux

Aplica-se a: ✔️ VMs ✔️ do Windows Conjuntos ✔️ de escala flexíveis Conjuntos de escalas uniformes

O Scheduled Events é um Azure Metadata Service que dá tempo à aplicação para se preparar para a manutenção da máquina virtual (VM). Fornece informações sobre os próximos eventos de manutenção (por exemplo, reiniciar) para que a aplicação possa preparar-se e limitar a interrupção. Está disponível para todos os tipos de Máquinas Virtuais do Azure, incluindo PaaS e IaaS no Windows e no Linux.

Para obter informações sobre eventos agendados no Linux, consulte Eventos agendados para VMs Linux.

Os eventos agendados fornecem notificações proativas sobre eventos futuros, para obter informações reativas sobre eventos que já aconteceram, consulte Informações de disponibilidade da VM no Azure Resource Graph e Criar regra de alerta de disponibilidade para a máquina virtual do Azure.

Porquê utilizar os Eventos Agendados?

Muitas aplicações podem beneficiar do tempo de preparação para a manutenção das VMs. O tempo pode ser utilizado para executar tarefas específicas da aplicação que melhorem a disponibilidade, a fiabilidade e a capacidade de serviço, incluindo:

• Ponto de verificação e restauro.
• Esvaziamento de ligações.
• Ativação pós-falha da réplica primária.
• Remoção de um conjunto de balanceadores de carga.
• Registo de eventos.
• Encerramento correto.

Com o Scheduled Events, a sua aplicação pode saber quando ocorrerá a manutenção e acionar tarefas para limitar o respetivo impacto.

O Scheduled Events fornece eventos nos seguintes casos de utilização:

• Manutenção iniciada pela plataforma (por exemplo, reinicialização de VM, migração ao vivo ou atualizações de preservação de memória para host).
• A máquina virtual está sendo executada em hardware de host degradado que está previsto para falhar em breve.
• A máquina virtual estava sendo executada em um host que sofreu uma falha de hardware.
• Manutenção iniciada pelo usuário (por exemplo, um usuário reinicia ou reimplanta uma VM).
• Expulsões de instâncias de VM Spot e Conjunto de dimensionamento Spot.

O básico

O Serviço de Metadados expõe informações sobre a execução de VMs usando um ponto de extremidade REST acessível de dentro da VM. As informações estão disponíveis por meio de um IP não roteável e não são expostas fora da VM.

Âmbito

Os eventos agendados são entregues e podem ser reconhecidos por:

• Máquinas virtuais autônomas.
• Todas as VMs em um serviço de nuvem do Azure (clássico).
• Todas as VMs em um conjunto de disponibilidade.
• Todas as VMs em um grupo de posicionamento de conjunto de escala.

Os Eventos Agendados para todas as máquinas virtuais (VMs) em um Conjunto de Disponibilidade inteiro ou um Grupo de Posicionamento para um Conjunto de Dimensionamento de Máquina Virtual são entregues a todas as outras VMs no mesmo grupo ou conjunto, independentemente do uso da Zona de Disponibilidade.

Como resultado, verifique o Resources campo no evento para identificar quais VMs são afetadas.

Descoberta de ponto de extremidade

Para VMs habilitadas para VNET, o Serviço de Metadados está disponível a partir de um IP estático não roteável, 169.254.169.254. O ponto de extremidade completo para a versão mais recente dos Eventos Agendados é:

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

Se a VM não for criada em uma Rede Virtual, os casos padrão para serviços de nuvem e VMs clássicas, será necessária lógica adicional para descobrir o endereço IP a ser usado. Para saber como descobrir o ponto de extremidade do host, consulte este exemplo.

Disponibilidade de versão e região

O serviço Eventos agendados tem controle de versão. As versões são obrigatórias; A versão atual é 2020-07-01.

Ativando e desativando eventos agendados

Os Eventos Agendados estão ativados para o seu serviço na primeira vez que faz um pedido de eventos. Você deve esperar uma resposta atrasada em sua primeira chamada de até dois minutos e você começará a receber eventos dentro de 5 minutos. Os Eventos Agendados serão desativados para o seu serviço se ele não fizer uma solicitação ao ponto de extremidade por 24 horas.

Manutenção iniciada pelo utilizador

A manutenção de VM iniciada pelo usuário por meio do portal do Azure, API, CLI ou PowerShell resulta em um evento agendado. Em seguida, você pode testar a lógica de preparação da manutenção em seu aplicativo e seu aplicativo pode se preparar para a manutenção iniciada pelo usuário.

Se você reiniciar uma VM, um evento com o tipo Reboot será agendado. Se você reimplantar uma VM, um evento com o tipo Redeploy será agendado. Normalmente, os eventos com uma fonte de eventos do usuário podem ser aprovados imediatamente para evitar um atraso nas ações iniciadas pelo usuário. Recomendamos que uma VM primária e secundária se comunique e aprove eventos agendados gerados pelo usuário caso a VM primária pare de responder. A aprovação imediata de eventos evita atrasos na recuperação do seu aplicativo de volta a um bom estado.

Eventos agendados para Conjuntos de Escala de Máquina Virtual Atualizações ou reimagens do SO convidado são suportados para tamanhos de VM de uso geral que suportam apenas atualizações de preservação de memória. Não funciona para as séries G, M, N e H. Os eventos agendados para Conjuntos de Escala de Máquina Virtual, atualizações e reimagens do SO convidado são desativados por padrão. Para habilitar eventos agendados para essas operações em tamanhos de VM suportados, primeiro habilite-os usando OSImageNotificationProfile.

Utilizar a API

Visão geral de alto nível

Há dois componentes principais para lidar com eventos agendados, preparação e recuperação. Todos os eventos agendados atuais que afetam uma VM estão disponíveis para leitura por meio do ponto de extremidade de Eventos Agendados do IMDS. Quando o evento atinge um estado terminal, ele é removido da lista de eventos. O diagrama a seguir mostra as várias transições de estado que um único evento agendado pode experimentar:

Para eventos no estado EventStatus:"Agendado", você precisará tomar medidas para preparar sua carga de trabalho. Quando a preparação estiver concluída, você deverá aprovar o evento usando a API de evento agendada. Caso contrário, o evento será aprovado automaticamente quando o tempo NotBefore for atingido. Se a VM estiver na infraestrutura compartilhada, o sistema aguardará que todos os outros locatários no mesmo hardware também aprovem o trabalho ou o tempo limite. Depois que as aprovações são coletadas de todas as VMs afetadas ou o tempo NotBefore é atingido, o Azure gera uma nova carga de evento agendada com EventStatus:"Started" e dispara o início do evento de manutenção. Quando o evento atinge um estado terminal, ele é removido da lista de eventos. Isso serve como o sinal para o cliente recuperar suas VMs.

Abaixo está o código psudeo demonstrando um processo de como ler e gerenciar eventos agendados em seu aplicativo:

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

Como os eventos agendados são frequentemente usados para aplicativos com requisitos de alta disponibilidade, há alguns casos excecionais que devem ser considerados:

1. Quando um evento agendado for concluído e removido da matriz, não haverá mais impactos sem um novo evento, incluindo outro evento EventStatus:"Scheduled"
2. O Azure monitoriza as operações de manutenção em toda a frota e, em circunstâncias raras, determina que uma operação de manutenção apresenta um risco demasiado elevado para ser aplicada. Nesse caso, o evento agendado vai diretamente de "Agendado" para ser removido da matriz de eventos
3. No caso de falha de hardware, o Azure ignora o estado "Agendado" e passa imediatamente para o estado EventStatus:"Started".
4. Enquanto o evento ainda estiver no estado EventStatus:"Started", pode haver outro impacto de uma duração mais curta do que o anunciado no evento agendado.

Como parte da garantia de disponibilidade do Azure, as VMs em diferentes domínios de falha não serão afetadas por operações de manutenção de rotina ao mesmo tempo. No entanto, eles podem ter operações serializadas uma após a outra. As VMs em um domínio de falha podem receber eventos agendados com EventStatus:"Scheduled" logo após a conclusão da manutenção de outro domínio de falha. Independentemente da arquitetura escolhida, continue sempre verificando novos eventos pendentes em suas VMs.

Embora os tempos exatos dos eventos variem, o diagrama a seguir fornece uma diretriz aproximada de como uma operação de manutenção típica procede:

• EventStatus:"Agendado" para aprovação Tempo limite: 15 minutos
• Duração do impacto: 7 segundos
• EventStatus:"Iniciado" para Concluído (evento removido da matriz Eventos): 10 minutos

Todas as operações que afetam a disponibilidade da VM resultarão em um evento agendado, no entanto, nem todos os eventos agendados aparecerão em outras superfícies do Azure, como Logs de Atividade do Azure ou Integridade de Recursos. Verificar eventos agendados regularmente garantirá que você tenha as informações mais atualizadas sobre quaisquer impactos futuros em suas VMs.

Cabeçalhos

Ao consultar o Serviço de Metadados, você deve fornecer o cabeçalho Metadata:true para garantir que a solicitação não tenha sido redirecionada involuntariamente. O Metadata:true cabeçalho é necessário para todas as solicitações de eventos agendados. A falha ao incluir o cabeçalho na solicitação resulta em uma resposta "Solicitação incorreta" do Serviço de Metadados.

Consulta de eventos

Você pode consultar eventos agendados fazendo a seguinte chamada:

Amostra de Bash

curl -H Metadata:true http://169.254.169.254/metadata/scheduledevents?api-version=2020-07-01

Exemplo do 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

Exemplo de 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

Uma resposta contém uma matriz de eventos agendados. Uma matriz vazia significa que, atualmente, nenhum evento está agendado. No caso em que há eventos agendados, a resposta contém uma matriz de eventos.

{
    "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},
        }
    ]
}

Propriedades do evento

Agendamento de eventos

Cada evento é agendado um período mínimo de tempo no futuro com base no tipo de evento. Esse tempo é refletido na propriedade de NotBefore um evento.

Isso significa que você pode detetar um cronograma futuro de evento pelo menos pelo tempo mínimo de aviso prévio antes do evento ocorrer. Uma vez que um evento é agendado, ele será movido para o Started estado depois de ter sido aprovado ou o NotBefore tempo passar. No entanto, em casos raros, a operação será cancelada pelo Azure antes de ser iniciada. Nesse caso, o evento será removido da matriz Eventos e o impacto não ocorrerá como agendado anteriormente.

Frequência de sondagem

Você pode pesquisar o ponto de extremidade em busca de atualizações com a frequência ou a frequência que desejar. No entanto, quanto maior o tempo entre as solicitações, mais tempo você potencialmente perde para reagir a um evento futuro. A maioria dos eventos tem 5 a 15 minutos de antecedência, embora em alguns casos o aviso prévio possa ser de apenas 30 segundos. Para garantir que você tenha o máximo de tempo possível para tomar medidas atenuantes, recomendamos que você pesquise o serviço uma vez por segundo.

Iniciar um evento

Depois de saber de um evento futuro e concluir sua lógica para o desligamento normal, você pode aprovar o evento pendente fazendo uma POST chamada para o Serviço de Metadados com EventId. Essa chamada indica ao Azure que ele pode reduzir o tempo mínimo de notificação (quando possível). O evento pode não começar imediatamente após a aprovação, em alguns casos o Azure requer a aprovação de todas as VMs hospedadas no nó antes de prosseguir com o evento.

O exemplo JSON a seguir é esperado no corpo da POST solicitação. O pedido deve conter uma lista de StartRequests. Cada StartRequest um contém EventId para o evento que você deseja acelerar:

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

O serviço sempre retorna um código de sucesso 200 se tiver passado uma ID de evento válida, mesmo que outra VM já tenha aprovado o evento. Um código de erro 400 indica que o cabeçalho da solicitação ou a carga útil estava malformada.

Amostra de 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

Exemplo do 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

Exemplo de 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

Exemplos de respostas

Os eventos a seguir são um exemplo que foi visto por duas VMs que foram migradas ao vivo para outro nó.

O DocumentIncarnation está mudando toda vez que há novas informações no Events. Uma aprovação do evento permitiria que o congelamento prosseguisse tanto para WestNO_0 quanto para WestNO_1. O DurationInSeconds de -1 indica que a plataforma não sabe quanto tempo a operação levará.

{
    "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":  [
               ]
}

Exemplo de Python

O exemplo a seguir consulta o Serviço de Metadados para eventos agendados e aprova cada evento pendente:

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

Próximos passos

• Analise os exemplos de código de Eventos Agendados no repositório GitHub de Eventos Agendados de Metadados da Instância do Azure.
• Analise os exemplos de código Node.js Eventos Agendados no repositório GitHub de Exemplos do Azure.
• Leia mais sobre as APIs disponíveis no Serviço de Metadados de Instância.
• Saiba mais sobre a manutenção planejada para máquinas virtuais do Windows no Azure.
• Saiba como monitorar eventos agendados para suas VMs por meio do Log Analytics.
• Saiba como registrar eventos agendados usando Hubs de Eventos do Azure no repositório GitHub de Exemplos do Azure.