Compartilhar via

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

  • Artigo

Parte do ciclo de vida do cluster do AKS envolve a execução de atualizações periódicas para a última versão do Kubernetes. É importante que você aplique as versões de segurança mais recentes e atualize para obter os recursos mais recentes. Este artigo mostra como verificar e aplicar upgrades ao seu cluster do AKS.

Atualizações de versões do Kubernetes

Ao atualizar um cluster do AKS com suporte, você não pode ignorar as versões secundárias do Kubernetes. Você deve realizar toas as atualizações sequencialmente por número de versão principal. Por exemplo, os upgrades entre 1.14.x ->1.15.x ou 1.15.x ->1.16.x são permitidos. 1.14.x ->1.16.x não são permitidas. Você só pode ignorar várias versões ao atualizar de uma versão sem suporte de volta para uma versão com suporte. Por exemplo, você pode fazer um upgrade de uma versão 1.10.x sem suporte para uma versão 1.12.x com suporte, se estiver disponível.

Ao realizar um upgrade de uma versão sem suporte que ignora duas ou mais versões secundárias, a funcionalidade do upgrade não é garantida e está excluída dos acordos de nível de serviço e da garantia limitada. Se sua versão estiver muito desatualizada, recomendamos que, em vez de atualizar, você recrie seu cluster.

Antes de começar

  • Se você estiver usando a CLI do Azure, este artigo vai requerer a CLI do Azure versão 2.34.1 ou posterior. 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 artigo vai requerer o Azure PowerShell versão 5.9.0 ou posterior. Execute Get-InstalledModule -Name Az para encontrar a versão. Se precisar instalar ou atualizar, consulte Instalar o Azure PowerShell.
  • Executar operações de atualização exige a função RBAC Microsoft.ContainerService/managedClusters/agentPools/write. Para obter mais informações sobre as funções RBAC do Azure, confira Operações de um provedor de recursos do Azure.
  • A partir das versões 1.30 do Kubernetes e 1.27 LTS, as APIs beta serão desabilitadas por padrão quando você atualizar para elas.

Aviso

Uma atualização do cluster do AKS dispara o isolamento e esvaziamento de seus nós. Se você tiver uma cota de computação baixa disponível, o upgrade poderá falhar. Para obter mais informações, confira aumentar cotas.

Verificação de atualizações disponíveis do cluster do AKS

Observação

Para se manter atualizado quanto às correções, versões e atualizações do AKS, confira o rastreador de versão do AKS.

  • Verifique quais versões do Kubernetes estão disponíveis para seu cluster usando o comando az aks get-upgrades.

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

    O exemplo de saída a seguir mostra a versão atual como 1.26.6 e lista as versões disponíveis em upgrades:

    {
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.26.6",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.3"
      }
    ]
  },
  ...
}

Solucionar problemas de mensagens de erro de atualização do cluster de AKS

A saída de exemplo a seguir significa que a extensão appservice-kube não é compatível com sua versão da CLI do Azure (é necessário no mínimo, a versão 2.34.1):

The 'appservice-kube' extension is not compatible with this version of the CLI.
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

Se você receber essa saída, precisará atualizar a versão da sua CLI do Azure. O comando az upgrade foi adicionado à versão 2.11.0 e não funciona nas versões anteriores a 2.11.0. Você pode ser atualizar versões mais antigas reinstalando a CLI do Azure, conforme descrito em Instalar a CLI do Azure. Se a sua versão da CLI do Azure for 2.11.0 ou posterior, execute az upgrade para atualizar a CLI do Azure para a versão mais recente.

Se a sua CLI do Azure for atualizada e você receber a seguinte saída de exemplo, isso significará que nenhuma atualização está disponível:

ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

Se nenhuma atualização estiver disponível, crie um novo cluster com uma versão com suporte do Kubernetes e migre as suas cargas de trabalho do cluster existente para o novo cluster. O AKS não oferece suporte ao upgrade de um cluster para uma versão mais recente do Kubernetes quando az aks get-upgrades mostra que não há atualizações disponíveis.

Atualizar um cluster AKS

Durante o processo de atualização do cluster, o AKS executa as seguintes operações:

  • adicionar um novo nó de buffer (ou tantos nós quantos estiverem configurados em pico máximo) ao cluster que executa a versão do Kubernetes especificada.
  • Isole e esvazie 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.
  • Para pods de execução prolongada, você pode configurar o tempo limite de esvaziamento do nó, o que permite um tempo de espera personalizado para o despejo de pods e o término normal por nó. Se não for especificado, o padrão será 30 minutos. O valor mínimo de tempo limite permitido é de 5 minutos.
  • 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.
  • Opcionalmente, você pode definir uma duração de tempo para aguardar entre esvaziar um nó e continuar a refazer a imagem e passar para o próximo nó. Um intervalo curto permite que você conclua outras tarefas, como verificar a integridade do aplicativo de um painel do Grafana durante o processo de atualização. Recomendamos um curto período para o processo de atualização, o mais próximo possível de 0 minuto. Caso contrário, um tempo de estabilização de nó maior afetará o tempo de descoberta de um problema. O valor mínimo de tempo de estabilização é de 0 minuto, com um máximo de 30 minutos. Se não for especificado, o valor padrão será 0 minuto.
  • 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.

  1. Atualize seu cluster usando o comando az aks upgrade.

    az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version <KUBERNETES_VERSION>

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

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

    O seguinte exemplo de saída mostra que o cluster agora está executando a versão 1.27.3:

    Name          Location    ResourceGroup    KubernetesVersion    ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  -------------------  ----------------------------------------------
myAKSCluster  eastus      myResourceGroup  1.27.3               Succeeded            myakscluster-dns-379cbbb9.hcp.eastus.azmk8s.io

Definir o canal de atualização automática

Você pode definir um canal de atualização automática em seu cluster. Para obter mais informações, confira Atualizar automaticamente um cluster do AKS.

Personalizar a atualização de pico de nós

Importante

  • Os picos de nós exigem uma cota de assinatura com a contagem de pico máximo solicitada para cada operação de atualização. Por exemplo, um cluster que tem cinco pools de nós, cada um com uma contagem de quatro nós, tem um total de 20 nós. Se cada pool de nós tiver um valor de pico máximo de 50%, uma cota de computação e IP adicional de 10 nós (2 nós * 5 pools) será necessária para concluir a atualização.

  • A configuração de pico máximo em um pool de nós é persistente. Atualizações posteriores do Kubernetes ou da versão do nó usarão essa configuração. Você pode alterar o valor do aumento súbito máximo para seus pools de nós a qualquer momento. Para pools de nós de produção, recomendamos uma configuração de max-surge de 33%.

  • Se você estiver usando a CNI do Azure, verifique se há IPs disponíveis na sub-rede para atender aos requisitos de IP da CNI do Azure.

O AKS configura os upgrades para aumentarem subitamente com um nó extra por padrão. Um valor padrão de um para as configurações do aumento súbito máximo permite que o AKS minimize a interrupção da carga de trabalho criando um nó extra antes de isolar/drenar os aplicativos existentes para substituir um nó com versão mais antiga. Você pode personalizar o valor do aumento súbito máximo por pool de nós. Quando você aumenta o valor do aumento súbito máximo, o processo de upgrade é concluído mais rapidamente, mas você poderá experimentar interrupções durante o processo.

Por exemplo, um valor do aumento súbito máximo de 100% proporciona o processo de atualização mais rápido possível, mas também faz com que todos os nós no pool de nós sejam drenados simultaneamente. Talvez você queira usar um valor alto, como este, para ambientes de teste. Para pools de nós de produção, recomendamos uma configuração max_surge de 33%.

O AKS aceita valores inteiros e um valor percentual para o pico máximo. Um inteiro, como 5, indica uma sobretensão de cinco nós extras. Um valor de 50% indica um valor de sobretensão da metade da contagem atual de nós no pool. Os valores percentuais da sobretensão máxima podem ser de no mínimo 1% e no máximo 100%. Um valor percentual é arredondado para cima, para a contagem de nós mais próxima. Se o valor máximo de aumento for maior do que o número necessário de nós a serem atualizados, o número de nós a serem atualizados será usado como valor máximo de aumento. Durante uma atualização, o valor de sobretensão máxima pode ser de, no mínimo, 1 e, no máximo, igual ao número de nós no pool de nós. Você pode configurar valores maiores, mas não pode configurar um número máximo de nós usados para o aumento súbito máximo que seja maior do que o número de nós no pool no momento do upgrade.

Configurar o valor do aumento súbito máximo

  • Configure o valor do aumento súbito máximo para os pools de nós novos ou existentes usando os comandos az aks nodepool add ou az aks nodepool update.

    # Set max surge for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%

# Update max surge for an existing node pool 
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 5

Definir o valor de tempo limite de esvaziamento do nó

Às vezes, você pode ter uma carga de trabalho de execução prolongada em um determinado pod e ela não pode ser reagendada para outro nó durante o runtime, por exemplo, uma carga de trabalho de estado com uso intensivo de memória que deve terminar de ser executada. Nesses casos, você pode configurar um tempo limite de esvaziamento do nó que o AKS respeitará no fluxo de trabalho de atualização. Se nenhum valor de tempo limite de esvaziamento do nó for especificado, o padrão será 30 minutos. O valor mínimo permitido de tempo limite de drenagem é de 5 minutos.

Se o valor temporal de drenagem for ultrapassado e os pods ainda estiverem em execução, a operação de atualização será interrompida. Qualquer operação PUT subsequente deve retomar a atualização interrompida. Também é recomendável que os pods de execução prolongada configurem o [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/].

  • Defina um tempo limite de esvaziamento de nós para pools de nós novos ou existentes usando o comando az aks nodepool add ou az aks nodepool update.

    # Set drain timeout for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster  --drain-timeout 100

# Update drain timeout for an existing node pool
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --drain-timeout 45

Definir o valor do tempo de estabilização do nó

Para permitir uma duração de tempo para aguardar entre esvaziar um nó e continuar a refazer a imagem e passar para o próximo nó, você pode definir o tempo de estabilização para um valor entre 0 e 30 minutos. Se nenhum valor de tempo de estabilização do nó for especificado, o padrão será 0 minuto.

  • Defina um tempo de estabilização de nós para pools de nós novos ou existentes usando o comando az aks nodepool add, az aks nodepool update ou az aks nodepool upgrade.

    # Set node soak time for a new node pool
az aks nodepool add --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10

# Update node soak time for an existing node pool
az aks nodepool update --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 5

# Set node soak time when upgrading an existing node pool
az aks nodepool upgrade --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 20

Ver os eventos de upgrade

  • Ver os eventos de upgrade usando o comando kubectl get events.

    kubectl get events

    O exemplo de saída de exemplo a seguir mostra alguns dos eventos listados acima durante um upgrade:

    ...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 1m45s Normal Upgrade node/aks-nodepool1-96663640-vmss000001   Soak duration 5m0s after draining node: aks-nodepool1-96663640-vmss000001
...
default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool nodepool1
...

Próximas etapas

Para saber como configurar upgrades automáticos, confira Configurar upgrades automáticos para um cluster do AKS.

Para obter uma discussão detalhada sobre as melhores práticas de atualização e outras considerações, veja Diretrizes de patch e atualização do AKS.