Azure Metadata Service: Scheduled Events for Linux VMs (Azure Metadata Service: Scheduled Events para VMs do Linux)
Aplica-se a: ✔️ Linux VMs ✔️ Conjuntos ✔️ de escala flexíveis Conjuntos de balanças 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 Windows, consulte Eventos agendados para VMs do Windows.
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.
Nota
Os Eventos Agendados estão geralmente disponíveis em todas as Regiões do Azure. Consulte Disponibilidade de versão e região para obter as informações de versão mais recentes.
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.
Nota
As máquinas virtuais aceleradas por GPU em um conjunto de escala usando 1 domínio de falha (FD = 1) só receberão eventos agendados para o recurso afetado. Os eventos não serão transmitidos para todas as VMs no mesmo grupo de posicionamento.
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.
| Versão | Tipo de versão | Regiões | Release Notes (Notas de Lançamento) |
|---|---|---|---|
| 2020-07-01 | Disponibilidade Geral | Todos | |
| 2019-08-01 | Disponibilidade Geral | Todos | |
| 2019-04-01 | Disponibilidade Geral | Todos | |
| 2019-01-01 | Disponibilidade Geral | Todos | |
| 2017-11-01 | Disponibilidade Geral | Todos | |
| 2017-08-01 | Disponibilidade Geral | Todos | |
| 2017-03-01 | Pré-visualizar | Todos |
Nota
As versões de pré-visualização anteriores de Eventos Agendados suportavam {latest} como a versão api. Este formato não é mais suportado e será preterido no futuro.
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:
- 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"
- 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 passará diretamente de "Agendado" para ser removido da matriz de eventos
- No caso de falha de hardware, o Azure ignora o estado "Agendado" e passa imediatamente para o estado EventStatus:"Started".
- 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
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
| Property | Description |
|---|---|
| Encarnação do documento | Inteiro que aumenta quando a matriz de eventos muda. Documentos com a mesma encarnação contêm as mesmas informações de evento, e a encarnação será incrementada quando um evento mudar. |
| EventId | Identificador global exclusivo para este evento. Exemplo:
|
| EventType | Impacto causado por este evento. Valores:
|
| ResourceType | Tipo de recurso afetado por esse evento. Valores:
|
| Recursos | Lista de recursos afetados por este evento. Exemplo:
|
| EventStatus | Estado deste evento. Valores:
Completed status ou similar é fornecido. O evento não é mais retornado quando o evento é concluído. |
| NotBefore | Tempo após o qual este evento pode começar. É garantido que o evento não começará antes deste horário. Ficará em branco se o evento já tiver começado Exemplo:
|
| Description | Descrição deste evento. Exemplo:
|
| Fonte de eventos | Iniciador do evento. Exemplo:
|
| DurationInSeconds | A duração esperada da interrupção causada pelo evento. Pode haver impactos secundários de menor duração durante a janela de impacto. Exemplo:
|
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.
| EventType | Pré-aviso mínimo |
|---|---|
| Congelar | 15 minutos |
| Reiniciar | 15 minutos |
| Voltar a implementar | 10 minutos |
| Terminar | Configurável pelo utilizador: 5 a 15 minutos |
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.
Nota
Em alguns casos, o Azure é capaz de prever falhas de host devido a hardware degradado e tentará mitigar a interrupção do seu serviço agendando uma migração. As máquinas virtuais afetadas receberão um evento agendado com um NotBefore que normalmente é de alguns dias no futuro. O tempo real varia dependendo da avaliação de risco de falha prevista. O Azure tenta avisar com 7 dias de antecedência quando possível, mas o tempo real varia e pode ser menor se a previsão for de que há uma grande chance de o hardware falhar iminentemente. Para minimizar o risco para o seu serviço no caso de o hardware falhar antes da migração iniciada pelo sistema, recomendamos que você reimplante sua máquina virtual o mais rápido possível.
Nota
Caso o nó host sofra uma falha de hardware, o Azure ignorará o período mínimo de aviso e iniciará imediatamente o processo de recuperação das máquinas virtuais afetadas. Isso reduz o tempo de recuperação no caso de as VMs afetadas não conseguirem responder. Durante o processo de recuperação, um evento será criado para todas as VMs afetadas com EventType = Reboot e EventStatus = Started.
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.
Nota
Os eventos não prosseguirão a menos que sejam aprovados através de uma mensagem POST ou do tempo NotBefore decorrido. Isso inclui eventos acionados pelo usuário, como reinicializações de VM a partir do portal do Azure.
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
Nota
Reconhecer um evento permite que o evento prossiga para todos Resources no evento, não apenas para a VM que reconhece o evento. Portanto, você pode optar por eleger um líder para coordenar o reconhecimento, que pode ser tão simples quanto a primeira máquina no Resources campo.
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 Linux no Azure.
- Saiba como registrar eventos agendados usando Hubs de Eventos do Azure no repositório GitHub de Exemplos do Azure.