Roll back node pool versions in Azure Kubernetes Service (AKS)

A funcionalidade de reversão de versão do pool de nós no Azure Kubernetes Service (AKS) permite recuperar de comportamentos imprevistos após atualizações do Kubernetes. Se surgirem problemas, pode reverter os pools de nós para a versão e à combinação anterior de imagens de nós do Kubernetes, garantindo a continuidade do negócio e minimizando a interrupção. Este artigo explica quando e como usar a funcionalidade de rollback, as suas capacidades e limitações, e as melhores práticas para ações pós-rollback.

Pré-requisitos

• CLI do Azure versão 2.88.0 ou posterior. Encontra a tua versão usando o az --version comando. Se precisares de instalar ou atualizar, vê Install CLI do Azure. A aks-preview extensão não é obrigatória.
• Versão 2026-04-01 da API ou posterior.

Funcionalidades suportadas para rollback de versões de node pool

A funcionalidade de rollback da versão do node pool suporta as seguintes capacidades:

Considerações e limitações do rollback em grupos de nós

Tenha em mente as seguintes limitações ao usar a funcionalidade de rolagem de pool de nós:

• Limitado apenas a alterações de versão. Outras alterações no agrupamento de nós não são revertidas.
• Não são permitidas operações simultâneas durante o rollback.
• Tens de desativar o canal automático de atualização do Kubernetes antes de reverter. Se o canal de atualização do sistema operativo do nó estiver ativado, o rollback da versão Kubernetes pode prosseguir, mas a imagem do nó anterior pode não ser restaurada. Desativa o canal de atualização do sistema operativo do nó quando precisares de reverter tanto a versão do Kubernetes como a imagem do nó.
• Disponível apenas durante sete dias após a conclusão da atualização.
• Não é possível realizar reversões consecutivas para retornar várias versões.
• O rollback não suporta reverter alterações ao SKU do sistema operativo. Se mudar o SKU do SO do seu pool de nós (por exemplo, de Ubuntu para Azure Linux), o rollback tentará restaurar a versão anterior da imagem do nó, que pertence a um SKU de SO diferente e será rejeitada. Para reverter uma alteração do SKU do SO, use o az aks nodepool update --os-sku comando em vez disso.

Tenha em mente as seguintes considerações ao usar rollback de pool de nós:

Porque usar rollback

O rollback fornece um mecanismo crítico de recuperação para ambientes de produção:

• Continuidade do negócio: Minimizar o tempo de inatividade quando as atualizações causam problemas inesperados
• Mitigação de riscos: Restaurar rapidamente configurações conhecidas como boas sem procedimentos complexos de recuperação
• Recuperação simplificada: Evite intervenção manual ou reconstrução de clusters a partir de backups

Quando usar o rollback do pool de nós

Considere a reversão como a sua opção de recuperação nos seguintes cenários:

• Ocorrem falhas de atualização: Problemas de infraestrutura, restrições de recursos ou problemas de compatibilidade impedem atualizações bem-sucedidas.
• As aplicações falham: As cargas de trabalho sofrem falhas críticas ou corrupção de dados com versões mais recentes do Kubernetes.
• O desempenho degrada-se: As novas versões causam latência inaceitável, problemas de largura de banda ou consumo de recursos.
• Surgem lacunas nos testes: surgem problemas em produção que não foram detetados durante os testes pré-produção.

Fluxo de trabalho de reversão de pools de nós

O diagrama seguinte ilustra o fluxo de trabalho de reversão do pool de nós:

O processo de rollback restaura todos os nós de um pool de nós ao estado da versão anterior. Aspetos-chave do fluxo de trabalho incluem:

• Abordagem tudo ou nada: Todos os nós devem reverter com sucesso à versão anterior para que a reversão seja concluída. Se algum nó falhar ao reverter, toda a operação falhará para comunicar claramente o estado do cluster, de forma semelhante à operação de atualização.
• Seguimento de progresso: Monitorize o estado de rollback usando Azure Registo de Atividade para o histórico de operações e a API de Estado de Operação para atualizações em tempo real.

Reverter a versão de um pool de nós

O comando rollback do CLI do Azure seleciona automaticamente a versão mais recente registada, também conhecida como N-1. Não podes usar o comando para selecionar uma versão arbitrária de Kubernetes ou imagem de nó, e não podes fazer rollbacks consecutivos para passar por várias versões anteriores.

1. Veja a configuração automática de atualização do cluster.

   az aks show \
       --name myAKSCluster \
       --resource-group myResourceGroup \
       --query autoUpgradeProfile
   

   Desative o canal automático de atualização do Kubernetes antes de reverter. Se precisares de restaurar a imagem do nó anterior, desativa também o canal de atualização do sistema operativo do nó.

2. Revise o alvo de rollback disponível usando o az aks nodepool get-rollback-versions comando.

   az aks nodepool get-rollback-versions \
       --name myNodePool \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster
   

   Se o comando não devolver versões, o pool de nós não tem um alvo de rollback elegível. O pool de nós deve ter sido atualizado nos sete dias anteriores, e a versão gravada do Kubernetes ainda deve ser suportada pelo AKS.

3. Reverte o pool de nós usando o az aks nodepool rollback comando.

   az aks nodepool rollback \
       --name myNodePool \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster
   

4. Verifique a versão Kubernetes, a versão da imagem do nó e o estado de provisionamento após o rollback terminar.

   az aks nodepool show \
       --name myNodePool \
       --resource-group myResourceGroup \
       --cluster-name myAKSCluster \
       --query '{provisioningState:provisioningState,kubernetesVersion:currentOrchestratorVersion,nodeImageVersion:nodeImageVersion}'
   

   Um rollback bem-sucedido retorna Succeeded e provisioningState mostra as versões gravadas do Kubernetes e da imagem do nó.

Se alteraste as definições automáticas de atualização do cluster antes do rollback, restaura as definições pretendidas depois de investigares e resolve o problema da atualização.

Monitorizar o estado do rollback do pool de nós

Pode usar os seguintes métodos para monitorizar o estado de uma operação de rollback de pool de nós e validar um rollback bem-sucedido:

• Consulta os registos de atividade do teu cluster.
• Procura eventos específicos relacionados com upgrades no teu cluster.
• Subscreva os eventos AKS com Azure Event Grid.
• Se subscrever um canal de atualização automática, pode usar o AKS Communication Manager para notificações de atualização.

Resolução de problemas no rollback do pool de nós

A tabela seguinte descreve os problemas comuns de rollback e como os resolver:

Boas práticas pós-rollback

Depois de reverter com sucesso o seu pool de nós, utilize as seguintes boas práticas para garantir estabilidade e segurança:

• Investigue a causa raiz: Identifique porque é que a atualização falhou antes de tentar outra atualização. Revise registos de aplicação, métricas de recursos e requisitos de compatibilidade.
• Teste em ambiente de pré-produção: Valide a versão mais recente num ambiente de desenvolvimento ou de teste para reproduzir e resolver problemas antes de atualizar a produção novamente.
• Planeie a sua nova atualização: Não fique indefinidamente na versão reversa. Agende uma nova atualização para manter patches de segurança e suporte:
  • Para questões críticas de segurança: Atualize novamente poucos dias após as correções serem validadas.
  • Para problemas de compatibilidade de aplicações: Atualize novamente dentro de semanas após ajustes de código.
  • Prazo máximo recomendado: 30 dias para evitar o acúmulo de vulnerabilidades de segurança.

Perguntas mais frequentes (FAQ)

Posso realizar outras operações durante um rollback de node pool?

Não, o rollback deve ser concluído antes de iniciar outras operações. Para realizar operações diferentes, aborte primeiro o rollback.

O rollback do node pool reverte tanto a versão do Kubernetes como a imagem do node?

Sim, o rollback reverte para a versão mais recente do Kubernetes e a respetiva imagem de nó. Se ambos os componentes forem alterados, o sistema restaura a versão anterior do Kubernetes com a última imagem de nó compatível com essa versão.

Posso reverter apenas a imagem do nó sem alterar a versão do pool de nós?

Sim, se fizeste apenas uma atualização da imagem do nó nos últimos sete dias (sem atualizar a versão do pool de nós), o rollback restaura a imagem anterior do disco rígido virtual (VHD) mantendo a mesma versão do Kubernetes.

Posso voltar atrás para uma versão que já não tem suporte?

Não, não podes voltar para uma versão Kubernetes que já não é suportada pelo AKS. Por exemplo, se o teu pool de nós estava na versão 1.27.9 (agora fora de suporte) e atualizaste para a 1.28.5, não podes voltar para a 1.27.9 porque já não está na lista de versões suportadas. Verifique sempre a política de suporte de versões do AKS Kubernetes para verificar a disponibilidade de versões.

Preciso de desativar o autoupgrade antes de realizar um rollback do node pool?

Sim, tens de desativar o canal automático de atualização do Kubernetes antes de fazer um rollback. Se ativares apenas o canal de atualização do sistema operativo do nó, o rollback da versão Kubernetes pode avançar, mas a imagem do nó anterior pode não ser restaurada. Desativa o canal de atualização do sistema operativo do nó quando precisares de reverter tanto a versão do Kubernetes como a imagem do nó.

Se o cluster estiver incluído num grupo de atualização num perfil de atualização automática do Azure Kubernetes Fleet Manager, deve também remover o cluster do grupo de atualização antes de realizar o rollback. Caso contrário, o processo de atualização automática pode atualizar automaticamente o teu pool de nós novamente após a conclusão do rollback.

Posso voltar atrás depois de mudar o SKU do sistema operativo (por exemplo, de Ubuntu para Azure Linux)?

Não. O rollback do node pool limita-se a alterações de versão e não reverte alterações ao SKU do SO. Após migrar de um SKU do SO para outro (por exemplo, Ubuntu para Azure Linux), a versão anterior da imagem do nó pertence ao antigo SKU do SO e é incompatível com a configuração atual. A operação de rollback rejeita a versão anterior da imagem com um erro semelhante a:

NodeImageVersion 'AKSUbuntu-2204gen2containerd-202602.13.5' is not accepted. NodeImageVersion can only be current version 'AKSAzureLinux-V3gen2-202602.13.5' or 'latest'

Para reverter o SKU do sistema operativo, use o az aks nodepool update comando com o --os-sku parâmetro. Para mais informações, consulte Restaurar a versão do seu sistema operativo.

Conteúdo relacionado

Para saber mais acerca da atualização de pools de nós no AKS, consulte os seguintes artigos:

• Configurar atualizações de conjuntos de nós azul-verde no Azure Kubernetes Service (AKS)
• Configurar atualizações progressivas para pools de nós do Azure Kubernetes Service (AKS)
• Atualização automática das imagens do sistema operativo dos nós no Azure Kubernetes Service (AKS)