Atualizar uma versão do Kubernetes do cluster do Amazon EKS

Quando uma nova versão do Kubernetes está disponível no Amazon EKS, você pode atualizar o cluster do Amazon EKS para a versão mais recente.

Importante

Depois de atualizar um cluster, não é possível revertê-lo uma versão anterior. Antes de atualizar para uma nova versão do Kubernetes, recomendamos revisar as informações em Versões Kubernetes do Amazon EKS e também as etapas de atualização neste tópico.

As novas versões do Kubernetes às vezes introduzem alterações significativas. Portanto, recomendamos que você teste o comportamento das aplicações com relação a uma nova versão do Kubernetes antes de atualizar os clusters de produção. Você pode fazer isso, criando um fluxo de trabalho de integração contínua para testar o comportamento da aplicação antes de mudar para uma nova versão do Kubernetes.

O processo de atualização consiste no Amazon EKS iniciar novos nós do servidor de API com a versão do Kubernetes atualizada para substituir os nós existentes. O Amazon EKS executa verificações padrão de integridade e prontidão da infraestrutura para o tráfego de rede nesses novos nós para confirmar que eles estão funcionando conforme o esperado. Porém, depois que você iniciou a atualização do cluster, não pode pausá-la nem interrompê-la. Se qualquer uma dessas verificações falhar, o Amazon EKS reverterá a implantação de infraestrutura e o cluster permanecerá na versão anterior do Kubernetes. A execução de aplicações não será afetada e o cluster nunca será deixado em um estado irrecuperável ou não determinista. O Amazon EKS faz backup regularmente de todos os clusters gerenciados, além de ter mecanismos para recuperar clusters, se necessário. Estamos avaliando e melhorando constantemente nossos processos de gerenciamento de infraestrutura do Kubernetes.

Para atualizar o cluster, o Amazon EKS requer até cinco endereços IP disponíveis das sub-redes que você especificou ao criar o cluster. O Amazon EKS cria novas interfaces de rede elásticas (interfaces de rede) de cluster em qualquer uma das sub-redes especificadas. Como as interfaces de rede podem ser criadas em sub-redes diferentes das interfaces de rede existentes, certifique-se de que as regras do grupo de segurança permitam a comunicação de cluster necessária para qualquer uma das sub-redes que você especificou ao criar o cluster. Se qualquer uma das sub-redes especificadas quando você criou o cluster não existir, não tiver endereços IP suficientes disponíveis ou não tiver regras de grupo de segurança que permitam a comunicação de cluster necessária, a atualização poderá falhar.

nota

Para garantir que o endpoint do servidor de API do seu cluster sempre esteja acessível, o Amazon EKS fornece um ambiente de gerenciamento Kubernetes com alta disponibilidade e executa atualizações contínuas das instâncias do servidor de API durante as operações de atualização. Para contabilizar a alteração de endereços IP das instâncias do servidor de API que oferecem suporte ao seu endpoint do servidor de API Kubernetes, você deve garantir que seus clientes do servidor de API gerenciem as reconexões de modo eficaz. Versões recentes do kubectl e das bibliotecas de cliente Kubernetes que têm suporte oficial executam esse processo de reconexão de modo transparente.

Atualizar a versão do Kubernetes de um cluster do Amazon EKS

Para atualizar a versão do Kubernetes para o cluster.

1. Compare a versão do Kubernetes do ambiente de gerenciamento do cluster com a versão do Kubernetes dos nós.

   • Obtenha a versão do Kubernetes para seu ambiente de gerenciamento do cluster.

     kubectl version
     

   • Obtenha a versão do Kubernetes para seus nós. Esse comando retorna todos os nós autogerenciados e gerenciados do Amazon EC2 e do Fargate. Cada Pod do Fargate é listado como seu próprio nó.

     kubectl get nodes
     

   Antes de atualizar o ambiente de gerenciamento para uma nova versão do Kubernetes, certifique-se de que a versão secundária do Kubernetes dos nós gerenciados e dos nós do Fargate no cluster sejam iguais à versão do ambiente de gerenciamento. Por exemplo, se o ambiente de gerenciamento estiver executando a versão 1.28 e um dos nós estiver executando a versão 1.27, será necessário atualizar os nós para a versão 1.28 antes de atualizar o ambiente de gerenciamento para 1.29. Também recomendamos que você atualize seus nós autogerenciados para a mesma versão do plano de controle antes de atualizar o plano de controle. Para obter mais informações, consulte Atualizar um grupo de nós gerenciados e Atualizações de nós autogerenciados. Se você tiver nós do Fargate com uma versão secundária inferior à versão do ambiente de gerenciamento, primeiramente exclua o Pod que é representado pelo nó. Em seguida, atualize seu ambiente de gerenciamento. Todos os demais Pods serão atualizados para a nova versão depois de reimplantados.

2. Se a versão do Kubernetes com a qual você implantou originalmente o cluster foi a versão 1.25 ou posterior do Kubernetes, pule essa etapa.

   Por padrão, o controlador de admissão de política de segurança de Pod é habilitado nos clusters do Amazon EKS. Antes de atualizar o cluster, certifique-se de que as políticas de segurança de Pod adequadas estejam em vigor. Isso acontece para evitar possíveis problemas de segurança. Você pode verificar a política padrão com o comando kubectl get psp eks.privileged.

   kubectl get psp eks.privileged
   

   Se receber o seguinte erro, consulte Política de segurança de Pod padrão do Amazon EKS antes de prosseguir.

   Error from server (NotFound): podsecuritypolicies.extensions "eks.privileged" not found

3. Se a versão do Kubernetes com a qual você implantou originalmente o cluster foi a versão 1.18 ou posterior do Kubernetes, pule essa etapa.

   Talvez seja necessário remover um termo descontinuado do seu manifesto CoreDNS.

   1. Verifique se o manifesto do CoreDNS tem uma linha que tenha apenas a palavra upstream.

      kubectl get configmap coredns -n kube-system -o jsonpath='{$.data.Corefile}' | grep upstream
      

      Se nenhuma saída for retornada, significa que o manifesto não tem a linha. Se este for o caso, pule para a próxima etapa. Se a palavra upstream for retornada, remova a linha.

   2. Remova a linha perto do topo do arquivo que só tem a palavra upstream no arquivo de configuração. Não mude mais nada no arquivo. Depois que a linha for removida, salve as alterações.

      kubectl edit configmap coredns -n kube-system -o yaml
      

4. Atualize seu cluster usando eksctl, o AWS Management Console ou a AWS CLI.

   Importante

   • Se você estiver atualizando para a versão 1.23 e usar volumes do Amazon EBS em seu cluster, será necessário instalar o driver de CSI do Amazon EBS no cluster antes de atualizar o cluster para a versão 1.23 a fim de evitar interrupções de workload. Para obter mais informações, consulte Kubernetes 1.23 e Driver da CSI do Amazon EBS.

   • O Kubernetes 1.24 e versões posteriores são usados containerd como o runtime padrão do contêiner. Se você estiver migrando para o containerd runtime e já tiver Fluentd configurado paraContainer Insights, deverá migrar Fluentd para ele Fluent Bit antes de atualizar seu cluster. Os analisadores Fluentd são configurados para analisar apenas mensagens de log no formato JSON. Ao contrário de dockerd, o runtime do containerd contêiner tem mensagens de log que não estão no formato JSON. Se você não migrar para Fluent Bit, alguns dos Fluentd's analisadores configurados gerarão muitos erros dentro do Fluentd contêiner. Para obter mais informações sobre migração, consulte Configurar Fluent Bit como um DaemonSet para enviar logs para o CloudWatch Logs.

   • Como o Amazon EKS executa um plano de controle de alta disponibilidade, você pode atualizar apenas uma versão secundária por vez. Para obter mais informações sobre esse requisito, consulte Política de suporte a versões e diferenciação de versões do Kubernetes. Suponha que a versão atual do cluster seja a 1.27 e você queira atualizar para a versão 1.29. Você deve primeiro atualizar o cluster versão 1.27 para versão 1.28 e depois atualizar o cluster versão 1.28 para a versão 1.29.

   • Analise a distorção de versão entre o kube-apiserver e o kubelet do Kubernetes em seus nós.

     • Com a versão 1.28 do Kubernetes e posteriores, o kubelet pode ter até três versões secundárias anteriores ao kube-apiserver. Consulte a política de distorção de versão upstream do Kubernetes.

     • Se o kubelet em seus nós gerenciados e nós do Fargate estiver em na versão 1.25 ou posterior do Kubernetes, você poderá atualizar seu cluster com até três versões à frente sem atualizar a versão do kubelet. Por exemplo, se a versão 1.25 do kubelet estiver ativa, você poderá atualizar a versão do cluster do Amazon EKS de 1.25 para 1.26 e de 1.27 para 1.28, enquanto o kubelet estiver na versão 1.25.

     • Se o kubelet nos nós gerenciados e do Fargate estiver em uma versão 1.24 ou anterior do Kubernetes, pode ser que haja apenas duas versões secundárias anteriores ao kube-apiserver. Em outras palavras, se o kubelet estiver na versão 1.24 ou anterior, você só poderá atualizar seu cluster até duas versões à frente. Por exemplo, se o kubelet estiver na versão 1.21, você poderá atualizar a versão do cluster do Amazon EKS de 1.21 para 1.22 e depois para 1.23, mas não poderá atualizar o cluster para a versão 1.24 enquanto o kubelet estiver na versão 1.21.

   • Como prática recomendada, antes de iniciar uma atualização, verifique se o kubelet em seus nós está na mesma versão do Kubernetes do seu ambiente de gerenciamento.

   • Se seu cluster estiver configurado com uma versão do Amazon VPC CNI plugin for Kubernetes anterior à 1.8.0, recomendamos atualizar o plug-in para a versão mais recente antes de atualizar seu cluster. Para atualizar o plug-in, consulte Trabalhando com o complemento Amazon VPC CNI plugin for Kubernetes do Amazon EKS.

   • Se você estiver atualizando o cluster para uma versão 1.25 ou posterior e tiver o AWS Load Balancer Controller implantado em seu cluster, atualize o controlador para a versão 2.4.7 ou posterior antes de atualizar sua versão do cluster para 1.25. Para obter mais informações, consulte as notas de versão do Kubernetes1,25.

   eksctl

   Este procedimento exige a versão eksctl 0.172.0 ou superior. Você pode verificar a versão com o seguinte comando:

   eksctl version
   

   Para obter instruções sobre como instalar e atualizar o eksctl, consulte Instalação na documentação do eksctl.

   Atualize a versão Kubernetes do ambiente de gerenciamento do Amazon EKS. Substitua my-cluster pelo nome do cluster. Substitua 1.29 pelo número da versão compatível com o Amazon EKS para a qual você deseja atualizar o cluster. Para obter a lista completa dos números das versões compatíveis, consulte Versões Kubernetes do Amazon EKS.

   eksctl upgrade cluster --name my-cluster --version 1.29 --approve
   

   O processo pode demorar alguns minutos para ser concluído.

   AWS Management Console

   1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/home#/clusters.

   2. Escolha o nome do cluster do Amazon EKS a ser atualizado e selecione Update cluster version (Atualizar versão do cluster).

   3. Em KubernetesKubernetes version (Versão do Kubernetes), selecione a versão para a qual o cluster será atualizado e escolha Update (Atualizar).

   4. Em Cluster name (Nome do cluster), insira o nome do seu cluster e escolha Confirm (Confirmar).

      O processo pode demorar alguns minutos para ser concluído.

   AWS CLI

   1. Atualize o cluster do Amazon EKS com o seguinte comando da AWS CLI. Substitua example values pelos seus próprios valores. Substitua 1.29 pelo número da versão compatível com o Amazon EKS para a qual você deseja atualizar o cluster. Para obter a lista completa dos números das versões compatíveis, consulte Versões Kubernetes do Amazon EKS.

      aws eks update-cluster-version --region region-code --name my-cluster --kubernetes-version 1.29
      

      Veja um exemplo de saída abaixo.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "InProgress",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.29"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      [...]
              "errors": []
          }
      }

   2. Monitore o status do cluster com o comando a seguir. Use o nome do cluster e o ID da atualização que o comando anterior retornou. Quando um status de Successful for exibido, significa que a atualização está concluída. O processo pode demorar alguns minutos para ser concluído.

      aws eks describe-update --region region-code --name my-cluster --update-id b5f0ba18-9a87-4450-b5a0-825e6e84496f
      

      Veja um exemplo de saída abaixo.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "Successful",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.29"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      [...]
              "errors": []
          }
      }

5. Depois que a atualização do cluster for concluída, atualize os nós para a mesma versão secundária que a do Kubernetes do cluster atualizado. Para obter mais informações, consulte Atualizações de nós autogerenciados e Atualizar um grupo de nós gerenciados. Todos os Pods novos iniciados no Fargate têm uma versão do kubelet que corresponde à versão do cluster. Os Pods existentes do Fargate não são alterados.

6. (Opcional) Se você implantou o Kubernetes Cluster Autoscaler no cluster antes de atualizá-lo, atualize o Cluster Autoscaler para a versão mais recente que corresponda à versão principal e secundária do Kubernetes para a qual você atualizou.

   1. Abra a página releases (versões) do Cluster Autoscaler em um navegador da Web e encontre a versão mais recente do Cluster Autoscaler que corresponda às versões principal e secundária do Kubernetes do cluster. Por exemplo, se a versão do Kubernetes do cluster for a versão 1.29, localize a versão mais recente do Cluster Autoscaler que comece com 1.29. Registre o número de versão semântico (1.29.n, por exemplo) dessa versão para usar na próxima etapa.

   2. Defina a tag de imagem do Cluster Autoscaler como a versão que você registrou na etapa anterior com o comando a seguir. Se necessário, substitua 1.29.n pelo seu próprio valor.

      kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:v1.29.n
      

7. (Clusters apenas com nós de GPU) Se o cluster tiver grupos de nós com suporte a GPU (por exemplo, p3.2xlarge), você deverá atualizar o DaemonSet do plug-in de dispositivo NVIDIA para Kubernetes no seu cluster. Substitua vX.X.X pela versão desejada de NVIDIA/k8s-device-plugin antes de executar o comando a seguir.

   kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/vX.X.X/nvidia-device-plugin.yml
   

8. Atualize os complementos Amazon VPC CNI plugin for Kubernetes, CoreDNS e kube-proxy. Recomendamos atualizar os complementos para as versões mínimas listadas nos tokens da conta de serviço.

   • Se você está usando complementos do Amazon EKS, selecione Clusters no console do Amazon EKS e, em seguida, selecione o nome do cluster que você atualizou no painel de navegação esquerdo. As notificações serão exibidas no console. Elas informam que uma nova versão está disponível para cada complemento que tenha uma atualização disponível. Para atualizar um complemento, selecione a guia Add-ons (Complementos). Em uma das caixas de um complemento que tenha uma atualização disponível, selecione Update now (Atualizar agora), selecione uma versão disponível e, em seguida, selecione Update (Atualizar).

   • Ou então, você pode usar a AWS CLI ou o eksctl para atualizar os complementos. Para ter mais informações, consulte Atualizar um complemento.

9. Se necessário, atualize a versão do kubectl. Você deve usar uma versão do kubectl que esteja em uma versão secundária de diferença do plano de controle do cluster do Amazon EKS. Por exemplo, um cliente do kubectl 1.28 funciona com clusters do Kubernetes 1.27, 1.28 e 1.29. É possível verificar a versão instalada atualmente com o comando a seguir.

   kubectl version --client