Tutorial – Atualizar um cluster do Serviço de Kubernetes do Azure (AKS)

Como parte do ciclo de vida do aplicativo e do cluster, talvez você queira atualizar para a versão mais recente disponível do Kubernetes. Você pode atualizar seu cluster do Serviço de Kubernetes do Azure (AKS) usando a CLI do Azure, o Azure PowerShell ou o portal do Azure.

Neste tutorial, você atualizará um cluster do AKS. Você aprenderá como:

  • Identifique as versões atuais e disponíveis do Kubernetes.
  • Atualize os nós do Kubernetes.
  • Valide um upgrade bem-sucedido.

Antes de começar

Nos tutoriais anteriores, você empacotou um aplicativo em uma imagem de contêiner e carregou a imagem do contêiner no Registro de Contêiner do Azure (ACR). Você também criou um cluster do AKS e implantou um aplicativo nele. Se você não concluiu essas etapas e deseja acompanhar este tutorial, comece com Tutorial 1: preparar um aplicativo para o AKS.

Se estiver usando a CLI do Azure, este tutorial exigirá a versão 2.34.1 ou posterior da CLI do Azure. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Se estiver usando o Azure PowerShell, este tutorial exigirá a versão 5.9.0 ou posterior do Azure PowerShell. Execute Get-InstalledModule -Name Az para encontrar a versão. Se precisar instalar ou atualizar, consulte Instalar o Azure PowerShell.

Para atualizar um cluster do AKS, você precisa da função Serviço de Kubernetes do Azure Colaborador ou permissões equivalentes.

Antes de atualizar, examine as notas de versão do AKS sobre alterações significativas e APIs preteridas. Verifique também os PDBs (orçamentos de indisponibilidade de Pods) da sua carga de trabalho, a cota disponível de computação e a capacidade de IPs da sub-rede para nós de expansão. Para obter mais informações, consulte Opções de atualização e recomendações para clusters do AKS.

Obter versões de cluster disponíveis usando o CLI do Azure

Antes de atualizar, verifique quais versões do Kubernetes estão disponíveis para o cluster usando o az aks get-upgrades comando.

az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster

A saída de exemplo a seguir mostra a versão atual de um cluster e lista as versões mais recentes em upgrades:

  {
    "agentPoolProfiles": null,
    "controlPlaneProfile": {
      "kubernetesVersion": "1.33.7",
      ...
      "upgrades": [
        {
          "isPreview": null,
          "kubernetesVersion": "1.34.10"
        },
        {
          "isPreview": null,
          "kubernetesVersion": "1.34.9"
        }
      ]
    },
    ...
  }

Obter versões de cluster disponíveis usando Azure PowerShell

  1. Antes de atualizar, verifique a versão e a região atuais do Kubernetes do cluster usando o Get-AzAksCluster cmdlet.

    Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, CurrentKubernetesVersion, Location

    A saída de exemplo a seguir mostra a versão e o local atuais do cluster:

    Name              CurrentKubernetesVersion      Location
----              ------------------------      --------
myAKSCluster      1.33.7                        westus2

  2. Liste as versões do Kubernetes disponíveis na região em que o cluster reside usando o Get-AzAksVersion cmdlet.

    Get-AzAksVersion -Location westus2 | Where-Object OrchestratorVersion

    A saída de exemplo a seguir mostra as versões regionais em OrchestratorVersion:

    Default     IsPreview     OrchestratorType     OrchestratorVersion
-------     ---------     ----------------     -------------------
                          Kubernetes               1.34.10
                          Kubernetes               1.34.9
True                      Kubernetes               1.33.7
...

    Para identificar possíveis destinos de atualização, compare versões mais recentes que a versão atual do cluster com as regras de atualização de versão do Kubernetes. Esse cmdlet lista a disponibilidade regional e não valida o caminho de atualização para um cluster específico.

Obter versões de cluster disponíveis usando o portal Azure

  1. Entre no portal do Azure.

  2. Navegue até o recurso de seu cluster do AKS.

  3. No menu de serviço, em Configurações, selecione Atualizações.

  4. Na versão do Kubernetes, selecione Versão de atualização.

    Captura de tela da opção Atualizar versão no portal do Azure.

  5. Na página Atualizar versão do Kubernetes, selecione o menu suspenso Versão do Kubernetes para exibir as versões disponíveis do Kubernetes para atualização.

    Captura de tela da atualização de versão com as versões de atualização disponíveis.

Se nenhuma atualização estiver disponível, o cluster poderá já estar na versão mais recente disponível ou a versão do cluster poderá estar fora da janela de suporte. Se a versão não tiver suporte e o AKS não oferecer uma atualização de recuperação, crie um novo cluster com uma versão do Kubernetes com suporte e migre suas cargas de trabalho. Para obter mais informações, consulte políticas de suporte do AKS para versões do Kubernetes.

Processo de atualização de cluster do AKS

Os nós do AKS são cuidadosamente isolados e drenados para minimizar interrupções potenciais aos aplicativos em execução. Durante esse processo, o AKS executa as etapas a seguir:

  • Adiciona um novo nó de buffer (ou quantos nós forem configurados no aumento máximo) ao cluster que executa a versão especificada do Kubernetes.
  • Isola e esvazia um dos nós antigos para minimizar a interrupção dos aplicativos em execução. Se você estiver usando uma sobretensão máxima, ele isola e esvazia tantos nós ao mesmo tempo quanto o número de nós de buffer especificado.
  • Quando o nó antigo é totalmente esvaziado, sua imagem será refeita para receber a nova versão e ele se torna o nó de buffer para o nó seguinte a ser atualizado.
  • Esse processo se repete até que todos os nós do cluster tenham sido atualizados.
  • No final do processo, o último nó do buffer é excluído, mantendo a contagem de nós de agente e o equilíbrio da zona existente.

Observação

Se nenhum patch for especificado, o cluster será automaticamente atualizado para o patch de GA mais recente da versão secundária especificada. Por exemplo, definir --kubernetes-version como 1.28 resulta na atualização do cluster para 1.28.9.

Para obter mais informações, consulte Atualizações de versão secundária do Kubernetes com suporte no AKS.

Você pode atualizar manualmente o cluster ou configurar atualizações automáticas de cluster. Configure atualizações automáticas de cluster para ajudar a manter seu cluster em uma versão com suporte do Kubernetes.

Atualizar o cluster manualmente usando o CLI do Azure

Atualize seu cluster usando o az aks upgrade comando. Este exemplo atualiza o cluster para a versão 1.34.10:

az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version 1.34.10

Observação

Os clusters não LTS com suporte devem ser atualizados sequencialmente, uma versão secundária de cada vez. Por exemplo, para atualizar de 1.33.x para 1.35.x, primeiro atualize para 1.34.x. Um cluster LTS pode ignorar versões secundárias ao migrar para uma versão LTS superior oferecida pelo AKS, se a atualização atender aos requisitos de compatibilidade entre versões e às checagens de validação. Para obter mais informações, consulte as regras de atualização de versão do Kubernetes.

A saída de exemplo a seguir mostra o resultado da atualização. O kubernetesVersion valor agora corresponde à versão especificada no comando de exemplo:

{
  ...
  "agentPoolProfiles": [
    {
      ...
      "count": 3,
      "currentOrchestratorVersion": "1.34.10",
      "maxPods": 110,
      "name": "nodepool1",
      "nodeImageVersion": "AKSUbuntu-2204gen2containerd-202608.26.0",
      "orchestratorVersion": "1.34.10",
      "osType": "Linux",
      "upgradeSettings": {
        "drainTimeoutInMinutes": null,
        "maxSurge": "10%",
        "nodeSoakDurationInMinutes": null,
        "undrainableNodeBehavior": null
      },
      "vmSize": "Standard_DS2_v2",
      ...
    }
  ],
  ...
  "currentKubernetesVersion": "1.34.10",
  "dnsPrefix": "myAKSClust-myResourceGroup-12ab34",
  "enableRbac": false,
  "fqdn": "myaksclust-myresourcegroup-12ab34-cd56e7fg.hcp.westus2.azmk8s.io",
  "id": "/subscriptions/<Subscription ID>/resourcegroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster",
  "kubernetesVersion": "1.34.10",
  "location": "westus2",
  "name": "myAKSCluster",
  "type": "Microsoft.ContainerService/ManagedClusters"
  ...
}

Atualizar o cluster manualmente usando Azure PowerShell

Atualize seu cluster usando o Set-AzAksCluster cmdlet. Este exemplo atualiza o cluster para a versão 1.34.10:

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -KubernetesVersion 1.34.10

Observação

Os clusters não LTS com suporte devem ser atualizados em sequência por versão secundária. Por exemplo, para atualizar de 1.33.x para 1.35.x, primeiro atualize para 1.34.x. Um cluster LTS pode ignorar versões menores ao migrar para uma versão LTS superior disponibilizada pelo AKS, se a atualização atender aos requisitos de compatibilidade entre versões e às checagens de validação. Para obter mais informações, consulte as regras de atualização de versão do Kubernetes.

A saída de exemplo a seguir mostra o resultado da atualização. O KubernetesVersion valor agora corresponde à versão especificada no cmdlet de exemplo:

...
ProvisioningState        : Succeeded
MaxAgentPools            : 100
KubernetesVersion        : 1.34.10
CurrentKubernetesVersion : 1.34.10
...
ResourceGroupName        : myResourceGroup
Name                     : myAKSCluster
Type                     : Microsoft.ContainerService/ManagedClusters
Location                 : westus2
Tags                     :

Atualizar o cluster manualmente usando o portal Azure

  1. No portal do Azure, navegue até o recurso do cluster do AKS.

  2. No menu de serviço, em Configurações, selecione Atualizações.

  3. Na versão do Kubernetes, selecione Versão de atualização.

    Captura de tela da opção Atualizar versão no portal do Azure.

  4. Na página Atualizar versão do Kubernetes, selecione o menu suspenso Versão do Kubernetes para exibir as versões disponíveis do Kubernetes para atualização.

    Captura de tela da atualização de versão com as versões de atualização disponíveis.

  5. Selecione a versão do Kubernetes para a qual deseja atualizar e, em seguida, selecione Salvar.

A duração da atualização depende de fatores como o número de nós, as configurações de expansão, as restrições de interrupção de cargas de trabalho, o tempo limite para drenagem e duração da imersão do nó. O tempo limite de drenagem padrão é de 30 minutos por nó e pode ser configurado de cinco minutos a 24 horas. A duração da imersão do nó pode adicionar zero a 30 minutos por nó. Para obter mais informações, consulte Personalizar as configurações de surge e indisponibilidade do pool de nós.

Configurar atualizações automáticas de cluster usando o CLI do Azure

Configurar atualizações automáticas de cluster usando Azure PowerShell

Configurar atualizações automáticas de cluster usando o portal Azure

Os clusters automáticos do AKS usam o stable canal e você não precisa configurar um canal. Para clusters padrão do AKS, selecione um canal com base na política de versão. Os canais stable e rapid avançam as versões menores do Kubernetes e ajudam a manter o cluster dentro da janela de versões com suporte. O patch canal instala apenas patches para a versão secundária atual e não avança o cluster para uma versão secundária mais recente.

Em um cluster do AKS Standard, defina o canal de autoupgrade usando o az aks update comando. O exemplo a seguir usa o stable canal:

az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable

Em um cluster do AKS Standard, defina o canal de autoupgrade usando o Set-AzAksCluster cmdlet. O exemplo a seguir usa o Stable canal:

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -AutoUpgradeChannel Stable

  1. No portal do Azure, navegue até o recurso do cluster do AKS.

  2. No menu de serviço, em Configurações, selecione Atualizações.

  3. Na versão do Kubernetes, selecione Versão de atualização.

    Captura de tela da opção Atualizar versão no portal do Azure.

  4. Para um cluster AKS Standard, na página Atualizar versão do Kubernetes, selecione a lista suspensa Atualização automática, selecione Habilitado com a versão estável e, em seguida, selecione Salvar.

    Captura de tela da página Atualizar versão do Kubernetes mostrando as opções de canal de atualização automática.

Para obter mais informações, confira Atualizar automaticamente um cluster do AKS (Serviço de Kubernetes do Azure).

Atualizar imagens de nó

O AKS fornece regularmente novas imagens de nó. As imagens dos nós do Linux são atualizadas semanalmente e as imagens dos nós do Windows são atualizadas mensalmente. É recomendável atualizar suas imagens de nó com frequência para usar os recursos e atualizações de segurança mais recentes do AKS. Para obter mais informações, confira Atualizar imagens de nó do AKS (Serviço de Kubernetes do Azure). Para configurar atualizações automáticas de imagem de nó, confira Atualizar automaticamente as imagens do sistema operacional do nó de cluster do AKS (Serviço de Kubernetes do Azure).

Ver os eventos de upgrade

Observação

Quando você atualiza o seu cluster, os seguintes eventos do Kubernetes podem ocorrer nos nós:

  • Aumentar: crie um nó de aumento.
  • Esvaziar: remova pods do nó. O AKS permite 30 minutos para drenar um nó por padrão. Você pode configurar o tempo limite de drenagem de cinco minutos a 24 horas.
  • Atualização: a atualização de um nó foi concluída com sucesso ou falhou.
  • Excluir: exclua um nó de aumento.

Use o kubectl get comando com um seletor de campo para exibir eventos do upgrader do AKS no namespace padrão.

kubectl get events --field-selector source=upgrader

A saída de exemplo a seguir mostra alguns dos eventos anteriores listados durante uma atualização:

LAST SEEN   TYPE      REASON    OBJECT                                   MESSAGE
...
5m          Normal    Drain     node/aks-nodepool1-12345678-vmss000000   Draining node: aks-nodepool1-12345678-vmss000000
5m          Normal    Upgrade   node/aks-nodepool1-12345678-vmss000000   Deleting node aks-nodepool1-12345678-vmss000000 from API server
4m          Normal    Upgrade   node/aks-nodepool1-12345678-vmss000000   Successfully reimaged node: aks-nodepool1-12345678-vmss000000
4m          Normal    Upgrade   node/aks-nodepool1-12345678-vmss000000   Successfully upgraded node: aks-nodepool1-12345678-vmss000000
4m          Normal    Drain     node/aks-nodepool1-12345678-vmss000000   Draining node: aks-nodepool1-12345678-vmss000000
...

Validar uma atualização usando o CLI do Azure

Confirme se a atualização foi bem-sucedida usando o az aks show comando.

az aks show --resource-group myResourceGroup --name myAKSCluster --output table

A saída de exemplo a seguir mostra que o cluster do AKS executa a versão do Kubernetes de destino:

Name          Location    ResourceGroup    KubernetesVersion    CurrentKubernetesVersion  ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  ------------------------  -------------------  ----------------------------------------------------------------
myAKSCluster  westus2      myResourceGroup  1.34.10              1.34.10                   Succeeded            myaksclust-myresourcegroup-12ab34-cd56e7fg.hcp.westus2.azmk8s.io

Validar uma atualização usando Azure PowerShell

Confirme se a atualização foi bem-sucedida usando o Get-AzAksCluster cmdlet.

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, Location, KubernetesVersion, ProvisioningState

A saída de exemplo a seguir mostra que o cluster do AKS executa a versão do Kubernetes de destino:

Name             Location     KubernetesVersion     ProvisioningState
----             --------     -----------------     -----------------
myAKSCluster     westus2       1.34.10               Succeeded

Validar uma atualização usando o portal Azure

  1. No portal do Azure, navegue até o recurso do cluster do AKS.
  2. Na página Visão geral , em Essentials, verifique a versão do Kubernetes para confirmar se a atualização foi bem-sucedida.

Excluir o cluster usando o CLI do Azure

Excluir o cluster usando Azure PowerShell

Excluir o cluster usando o portal Azure

Como este tutorial é a última parte da série, é aconselhável excluir seu cluster do AKS para evitar a geração encargos do Azure.

Remova o grupo de recursos, o serviço de contêiner e todos os recursos relacionados usando o az group delete comando.

az group delete --name myResourceGroup --yes --no-wait

Remova o grupo de recursos, o serviço de contêiner e todos os recursos relacionados usando o Remove-AzResourceGroup cmdlet.

Remove-AzResourceGroup -Name myResourceGroup
  1. No portal do Azure, navegue até o recurso do cluster do AKS.
  2. Na página Visão Geral, selecione Excluir.
  3. Na página Excluir confirmação do cluster, selecione Excluir.

Observação

Quando você excluir o cluster, a entidade de serviço do Microsoft Entra usada pelo cluster do AKS não será removida. Para obter as etapas para remover a entidade de serviço, confira Considerações sobre a entidade de serviço do AKS e sua exclusão. Se você usou uma identidade gerenciada, ela é administrada pela plataforma e não exige que você faça a provisão ou a rotação de nenhum segredo.

Próximas etapas

Neste tutorial, você fez upgrade do Kubernetes em um cluster do AKS. Você aprendeu a:

  • Identifique as versões atuais e disponíveis do Kubernetes.
  • Atualize os nós do Kubernetes.
  • Valide um upgrade bem-sucedido.

Para obter mais informações sobre o AKS, consulte a visão geral do AKS. Para obter orientação sobre como criar soluções completas com o AKS, confira as Diretrizes de solução do AKS.

  • Last updated on