Ajudar a melhorar esta página

Para contribuir com este guia de usuário, escolha o link Editar esta página no GitHub, disponível no painel direito de cada página.

Reverter um cluster para uma versão anterior do Kubernetes

Com a reversão da versão do Amazon EKS, você pode reverter o ambiente de gerenciamento do Kubernetes do seu cluster para a versão secundária anterior depois de realizar uma atualização local. Se você encontrar problemas após a atualização, como incompatibilidades de aplicações, uso de APIs obsoletas ou comportamento inesperado, você pode reverter para restaurar seu cluster a um estado bom conhecido.

Durante uma reversão, o Amazon EKS reverte o servidor da API do Kubernetes e os componentes do ambiente de gerenciamento para a versão anterior, preservando todos os dados do etcd, as workloads do cliente e os volumes persistentes.

O que é revertido

Os seguintes componentes são revertidos:

O que NÃO é revertido

Os seguintes componentes não são revertidos:

Pré-requisitos

Para que você possa reverter um cluster, todas as seguintes condições devem ser atendidas:

Além dos requisitos anteriores, certas condições impossibilitam a reversão, mesmo com o sinalizador --force. Essas condições incluem o seguinte: o cluster foi criado na versão atual, já se passaram mais de sete dias desde a atualização, o cluster já foi atualizado novamente para uma versão mais recente ou um recurso do EKS incompatível com versões anteriores foi habilitado no limite da versão atual.

Resumo

Confira a seguir o resumo de alto nível do processo de reversão do cluster do Amazon EKS:

Etapa 1: revisar insights de prontidão para reversão

O Amazon EKS avalia automaticamente seu cluster em relação a um conjunto de verificações pontuais de prontidão para reversão e identifica quaisquer problemas por meio de insights do cluster na categoria ROLLBACK_READINESS. Esses insights aparecem após a atualização e permanecem disponíveis durante a janela de elegibilidade para reversão de sete dias.

Visualização dos insights de prontidão para reversão

Console da AWS:

AWS CLI:

aws eks list-insights \
  --cluster-name my-cluster \
  --region us-west-2 \
  --filter '{"categories": ["ROLLBACK_READINESS"]}'

Para obter detalhes sobre um insight específico:

aws eks describe-insight \
  --cluster-name my-cluster \
  --region us-west-2 \
  --id <insight-id>

Atualização de insights

O Amazon EKS atualiza os insights a cada 24 horas. Você pode acionar manualmente uma atualização após resolver problemas escolhendo o botão Atualizar no console do Amazon EKS ou usando a CLI:

aws eks start-insights-refresh \
  --cluster-name my-cluster \
  --region us-west-2

Comportamento do status do insight

A tabela a seguir descreve o significado de cada status de insight e seu efeito na reversão:

Insights com o status de ERROR ou UNKNOWN bloqueiam a reversão. Insights com O status PASSING ou WARNING não impedem que você faça a reversão.

Verificações de prontidão para reversão

O Amazon EKS realiza um conjunto de verificações como parte dos insights de prontidão para reversão. Essas verificações avaliam a compatibilidade do uso da API (incluindo detecção de alterações em nível de campo), a integridade do cluster, o desvio da versão do kubelet, o desvio da versão do kube-proxy e a compatibilidade da versão do complemento. Para clusters que executam o Modo Automático do EKS, verificações adicionais avaliam os orçamentos de interrupção do NodePool, as anotações de não interrupção e as configurações de PodDisruptionBudget.

Usando o sinalizador --force

Se os insights de prontidão para reversão mostrarem o status de ERROR e você quiser continuar sem resolver os problemas, use o sinalizador --force para ignorar todas as verificações de insights:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --force \
  --region us-west-2

O sinalizador --force apenas ignora as verificações de insights. Ele não ignora as validações de pré-requisitos, como a janela de sete dias, a verificação da versão de criação ou a verificação de reversão sequencial. Para clusters do Modo Automático, --force não sobrescreve os controles de interrupção. Os orçamentos de interrupção do NodePool, os PDBs e as anotações de não interrupção ainda são respeitados.

Etapa 2: preparar nós de processamento

Antes de reverter o ambiente de gerenciamento, certifique-se de que seus nós de processamento sejam compatíveis com a versão de destino. A política de desvio de versão do Kubernetes exige que os nós de processamento não possam executar uma versão mais recente do que o ambiente de gerenciamento.

Modo Automático do EKS

Nenhuma ação necessária. Quando você inicia a reversão, o Amazon EKS faz a reverão automática dos nós no Modo Automático antes do ambiente de gerenciamento. Para obter mais informações, consulte Reversão de clusters do Modo Automático do EKS.

Grupos de nós gerenciados (MNG)

Você deve reverter seus grupos de nós gerenciados para a versão anterior antes de reverter o ambiente de gerenciamento. Usar a API UpdateNodegroupVersion:

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.30 \
  --region us-west-2

A atualização do grupo de nós respeita suas configurações de atualização definidas (maxUnavailable ou maxUnavailablePercentage) e a estratégia de atualização (Rolling ou Force).

Nós autogerenciados e nós híbridos

Você é responsável por reverter os nós autogerenciados e os nós híbridos. Atualize as AMIs ou configurações dos seus nós para usar a versão anterior do Kubernetes antes de reverter o ambiente de gerenciamento.

Fargate

A reversão de versão não é compatível com os nós de processamento do Fargate. Você pode reverter o ambiente de gerenciamento de um cluster que usa o Fargate, mas os pods do Fargate que executam a mesma versão do Kubernetes que o ambiente de gerenciamento acionam o insight de desvio de versão do kubelet com o status de ERROR.

O Amazon EKS não pode reverter automaticamente os pods do Fargate para uma versão mais antiga do kubelet.

Solução alternativa: se você tiver pods do Fargate executando a mesma versão do Kubernetes que o ambiente de gerenciamento, exclua esses pods antes de iniciar a reversão. Em seguida, reverta seu ambiente de gerenciamento. Todos os pods restantes são inicializados com a versão revertida quando você os reimplanta.

Como alternativa, use --force para ignorar a verificação de insights. No entanto, continuar com uma violação de desvio da versão do kubelet pode resultar em comportamento inesperado para suas workloads do Fargate até que esses pods sejam substituídos.

Etapa 3: reverter o ambiente de gerenciamento do cluster

Você pode iniciar uma reversão usando o Console da AWS, a AWS CLI ou a API do EKS.

Reverter um cluster usando o Console da AWS

A reversão leva alguns minutos para ser concluída. Para clusters do Modo Automático, a fase de reversão dos nós pode levar mais tempo. Para obter mais informações, consulte Reversão de clusters do Modo Automático do EKS.

Reverter um cluster usando a AWS CLI

Use o comando update-cluster-version existente com a versão anterior (N-1) do Kubernetes:

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --region us-west-2

Exemplo de resposta:

{
    "update": {
        "id": "e4091a28-ea14-48fd-a8c7-975aeb469e8a",
        "status": "InProgress",
        "type": "VersionRollback",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.16"
            }
        ],
        "createdAt": "2026-05-12T16:56:01.082000-04:00",
        "errors": []
    }
}

Etapa 4: monitorar o andamento da reversão

É possível monitorar o status da reversão do cluster usando o console do Amazon EKS ou a AWS CLI.

AWS CLI:

aws eks describe-update \
  --name my-cluster \
  --region us-west-2 \
  --update-id e4091a28-ea14-48fd-a8c7-975aeb469e8a

Console da AWS:

Transições de status

Para clusters padrão (sem o Modo Automático):

InProgress → Successful
InProgress → Failed

Para clusters do Modo Automático, o status do cluster permanece ACTIVE enquanto os nós são revertidos e muda para UPDATING somente quando a reversão do ambiente de gerenciamento começa. Use describe-update para acompanhar o progresso geral da reversão. Para obter mais informações, consulte Reversão de clusters do Modo Automático do EKS.

Quando um status de Successful for exibido, a reversão estará concluída.

Considerações e avisos

Os insights são de caráter pontual e fornecidos no melhor esforço

Os insights do cluster são avaliados no momento em que a reversão é acionada. Se você fizer alterações em seu cluster após a verificação dos insights, mas antes da conclusão da reversão (por exemplo, criar recursos usando novas APIs), essas alterações não serão capturadas pela verificação inicial do insight e poderão causar problemas após a conclusão da reversão.

Preservação de dados do etcd

O Amazon EKS preserva os dados do etcd durante a reversão. Os recursos incompatíveis ignorados pelo uso do sinalizador --force permanecem persistentes e não são coletados como resíduos.

Cobranças do suporte estendido

Se você reverter de uma versão com suporte padrão para uma versão com suporte estendido, seu cluster começará a gerar cobranças de suporte estendido. Por exemplo, se você atualizar de 1.30 (suporte estendido) para 1.31 (suporte padrão) e depois reverter para 1.30, as cobranças de suporte estendido serão retomadas.

Modelo de responsabilidade compartilhada para reversão

O Amazon EKS reverte o ambiente de gerenciamento do Kubernetes para a versão desejada. Como parte do modelo de responsabilidade compartilhada, você é responsável por verificar a compatibilidade da aplicação com a versão anterior:

Comportamento da reversão da pilha do CloudFormation

Se uma atualização da pilha do AWS CloudFormation falhar e acionar uma reversão da pilha, a reversão para uma versão de modelo anterior que especifica uma versão inferior do Kubernetes não acionará uma reversão da versão do cluster. A reversão de versão deve ser iniciada explicitamente por meio da API UpdateClusterVersion, da CLI ou do console.

Reversão e complementos

O Amazon EKS não reverte automaticamente as versões de complementos durante a reversão da versão do cluster. Você deve gerenciar as versões de complementos separadamente.

Antes de reverter o ambiente de gerenciamento:

Recursos relacionados