Como fazer o upgrade manual de um cluster ou pool de nós

Autopilot Padrão

---

Por padrão, os upgrades automáticos são ativados para clusters do Google Kubernetes Engine (GKE) e para pools de nós padrão do GKE.

Nesta página, explicamos como solicitar manualmente um upgrade ou downgrade do plano de controle ou dos nós de um cluster do GKE. É possível fazer upgrade da versão manualmente da seguinte maneira:

• Autopilot: faça upgrade da versão do plano de controle.
• Padrão: faça upgrade da versão do plano de controle e da versão do pool de nós.

Para fazer upgrade de um cluster, o GKE atualiza a versão que o plano de controle e os nós estão executando. Os clusters são atualizados para uma versão secundária mais recente (por exemplo, da 1.24 para a 1.25) ou para uma versão de patch mais recente (por exemplo, da 1.24.2-gke.100 para a 1.24.5-gke.200). Para mais informações, consulte Controle de versão e suporte do GKE.

Saiba mais sobre como os upgrades de cluster automáticos e manuais funcionam. Você também pode controlar quando os upgrades automáticos podem ou não ocorrer com a configuração de janelas e exclusões de manutenção.

Observação sobre a terminologia: os nós e o plano de controle de um cluster não executam necessariamente a mesma versão o tempo todo. Neste tópico, os termos upgrade de cluster e upgrade do plano de controle são usados de forma intercambiável e são diferentes de upgrades de nó.

Novas versões do GKE são anunciadas regularmente, e é possível receber avisos sobre as novas versões para as quais um cluster específico pode ser atualizado com notificações de cluster.

Para saber mais sobre as versões disponíveis, consulte Controle de versões. Para ver informações sobre clusters, consulte Arquitetura de cluster. Para conferir orientações sobre como fazer upgrade dos clusters, consulte Práticas recomendadas para fazer upgrade de clusters.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
  Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como este: One of [--zone, --region] must be supplied: Please specify location.

Salve seus dados em discos permanentes

Antes de fazer upgrade de um pool de nós, garanta que todos os dados que você quer manter estejam armazenados em um pod com volumes permanentes que usem discos permanentes. Em vez de apagados, os discos permanentes são desconectados durante os upgrades, e os dados deles são "distribuídos" entre os pods.

As seguintes restrições são relacionadas aos discos permanentes:

• Os pods estão em execução nos nós que precisam ser VMs do Compute Engine.
• Essas VMs precisam estar no mesmo projeto e zona do Compute Engine que o disco permanente.

Para saber como adicionar um disco permanente a uma instância de nó atual, consulte Como adicionar ou redimensionar discos permanentes zonais na documentação do Compute Engine.

Sobre o upgrade

Os upgrades do plano de controle e dos nós de um cluster são feitos separadamente.

Os planos de controle de cluster sempre são atualizados regularmente, independentemente de o cluster estar inscrito em um canal de lançamento ou não.

Para receber notificações de upgrade proativamente, consulte Receber notificações de cluster.

Limitações

Clusters Alpha não podem receber upgrade.

Versões compatíveis

As Notas de lançamento anunciam quando novas versões estão disponíveis e quando versões mais antigas não estão mais disponíveis. A qualquer momento, é possível listar todas as versões compatíveis de cluster e nó usando este comando:

gcloud container get-server-config

Se o cluster estiver inscrito em um canal de lançamento, será possível fazer upgrade para uma versão de patch em um canal de lançamento diferente com a mesma versão secundária do plano de controle. Por exemplo, é possível fazer upgrade do cluster da versão 1.21.12-gke.1700 no canal normal para 1.21.13-gke.900 no canal rápido. Para saber mais, consulte Executar versões de patch de um canal mais recente. Todos os clusters do Autopilot são registrados em um canal de lançamento.

Limitações de downgrade

É possível fazer downgrade da versão do cluster para uma versão anterior em determinados cenários.

Para mitigar um upgrade sem sucesso do plano de controle de cluster, é possível: fazer downgrade do plano de controle para uma versão de patch anterior se a versão for um lançamento de patch anterior à mesma versão secundária (em inglês). Por exemplo, se o plano de controle do cluster estiver executando o GKE 1.25.3-gke.400, será possível fazer downgrade do plano de controle para 1.25.2-gke.100, se essa versão ainda estiverdisponível.

Não é possível fazer downgrade de um plano de controle do cluster do Kubernetes para uma versão secundária anterior. Por exemplo, se o plano de controle executa a versão 1.25 do GKE, não é possível fazer downgrade para a versão 1.24. Se você tentar fazer isso, a seguinte mensagem de erro vai aparecer:

ERROR: (gcloud.container.clusters.upgrade) ResponseError: code=400,
message=Master cannot be upgraded to "1.24.3-gke.100": specified version is not
newer than the current version.

Não é possível fazer downgrade da versão secundária do plano de controle de um cluster. Por isso, recomendamostestar e qualificar upgrades de versão secundária com clusters em um ambiente de teste quando uma nova versão secundária é disponibilizada, mas antes da versão padrão. Isso é especialmente recomendado se o cluster for afetado por alterações significativas na próxima versão secundária, como a remoção de recursos ou APIs descontinuadas.

Para atenuar um upgrade com falha do pool de nós, é possível fazer downgrade de um pool de nós para uma versão anterior do patch ou uma versão secundária. Não faça o downgrade de nós para uma versão mais de duas versões secundárias atrás da versão do plano de controle do cluster.

Como fazer upgrade do cluster

O Google faz upgrade de clusters e nós automaticamente. Para ter mais controle sobre quais upgrades automáticos seu cluster e seus nós recebem, é possível inscrevê-lo em um canal de lançamento. Todos os clusters do Autopilot são registrados automaticamente em um canal de lançamento.

Para saber mais sobre como gerenciar a versão do GKE do seu cluster, consulte Upgrades.

Depois que uma nova versão estiver disponível, inicie um upgrade manual quando quiser.

Como fazer upgrade manual do plano de controle

Observação: não é possível fazer upgrade do cluster mais de uma versão secundária de cada vez. Por exemplo, é possível fazer upgrade de um cluster da versão 1.25 para 1.26, mas não diretamente de 1.25 para 1.27. Para mais informações, consulte Posso pular versões durante um upgrade de cluster?.

Ao iniciar um upgrade de cluster, não modifique a configuração do cluster por vários minutos, até que o plano de controle possa ser acessado novamente. Se você precisar evitar a inatividade durante os upgrades do plano de controle, use um cluster do Autopilot ou um cluster padrão regional. Essa operação não afeta a disponibilidade dos nós de trabalho em que as cargas de trabalho são executadas, já que permanecem disponíveis durante os upgrades do plano de controle.

É possível fazer upgrade manual do seu plano de controle do Autopilot ou Standard usando o Console do Google Cloud ou a Google Cloud CLI.

gcloud

Para ver as versões disponíveis para o plano de controle do seu cluster, execute o seguinte comando:

gcloud container get-server-config

Para fazer upgrade para a versão padrão do cluster, execute o seguinte comando:

gcloud container clusters upgrade CLUSTER_NAME --master

Para fazer upgrade para uma versão específica que não seja a padrão, especifique a sinalização --cluster-version como no seguinte comando:

gcloud container clusters upgrade CLUSTER_NAME --master \
    --cluster-version VERSION

Substitua VERSION pela versão em que você quer fazer upgrade do cluster. Use uma versão específica, como 1.18.17-gke.100, ou um alias de versão, como latest. Para mais informações, consulte Como especificar a versão do cluster.

Observação: se o cluster estiver inscrito em um canal de lançamento, o VERSION precisa ser uma versão secundária válida para o canal de lançamento ou uma versão do patch em um canal de lançamento mais recente. Todos os clusters do Autopilot são registrados em um canal de lançamento.

Console

Para atualizar manualmente o plano de controle do cluster, siga estas etapas:

1. Acesse a página do Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Clique no nome do cluster que você quer.

3. Em Princípios básicos do cluster, clique em Upgrade disponível ao lado de Versão.

4. Selecione a versão pretendida e clique em Salvar alterações.

Depois de fazer upgrade de um plano de controle padrão, é possível fazer upgrade dos nós dele. Por padrão, os nós padrão criados com o Console do Google Cloud têm o upgrade automático ativado. Isso acontece automaticamente. O Autopilot sempre faz o upgrade automático dos nós.

Como fazer downgrade de clusters

Observação: entenda as limitações antes de fazer downgrade de um cluster.

1. Defina uma exclusão de manutenção antes de fazer downgrade para impedir que o GKE faça upgrade do plano de controle automaticamente depois do downgrade.

2. Faça downgrade do plano de controle do cluster para uma versão de patch anterior:

    gcloud container clusters upgrade CLUSTER_NAME \
        --master --cluster-version VERSION
   

Observação: Se o cluster estiver inscrito em um canal de lançamento, o VERSION precisa ser uma versão do patch disponível para o canal de lançamento. Todos os clusters do Autopilot são registrados em um canal de lançamento.

Como desativar os upgrades automáticos do cluster

A segurança da infraestrutura é alta prioridade para o GKE e, como tal, planos de controle são atualizados regularmente e não pode ser desativada. No entanto, é possível aplicar janelas de manutenção e exclusões para suspender temporariamente os upgrades de planos de controle e nós.

Embora não seja recomendado, é possível desativar o upgrade automático do nó.

Como fazer upgrade de pools de nós

Por padrão, os nós de um cluster têm o upgrade automático ativado e é recomendável não desativá-lo. Os upgrades automáticos de nós garantem que o plano de controle e a versão do nó do cluster permaneçam sincronizados e em conformidade com a política de distorção de versão do Kubernetes, que garante que os planos de controle são compatíveis com nós com até duas versões secundárias mais antigas que o plano de controle. Por exemplo, os planos de controle do Kubernetes 1.29 são compatíveis com os nós do Kubernetes 1.27.

Com os upgrades de pool de nós do GKE, é possível escolher entre duas estratégias de upgrade configuráveis, ou seja, upgrades súbitos e upgrades azul-verde.

Escolha uma estratégia e use os parâmetros para ajustá-la de acordo com as necessidades do ambiente do cluster.

Enquanto um nó está sendo atualizado, o GKE interrompe a programação de novos pods nele e tenta programar seus pods em execução em outros nós. Isso é semelhante a outros eventos que recriam o nó, como ativar ou desativar um recurso no pool de nós.

Observação: durante os upgrades automáticos ou manuais de nós, PodDisruptionBudgets (PDBs) e o período de carência do encerramento do pod são respeitados por 1 hora no máximo. Se a programação dos pods em um nó não for possível depois desse período, o upgrade será iniciado mesmo assim. Se uma carga de trabalho exigir mais flexibilidade com encerramento otimizado, recomendamos o uso de upgrades azul-verde, que fornecem configurações para mais tempo de imersão para estender as verificações de PDB além do padrão de 1 hora. Para mais informações sobre o que esperar durante o encerramento do nó, consulte o tópico sobre Pods.

O upgrade será concluído apenas quando todos os nós forem recriados e o cluster assumir o estado desejado. Quando um nó recém-atualizado é registrado no plano de controle, o GKE o marca como programável.

As instâncias do novo nó executam a versão do Kubernetes desejada e também:

• A imagem do nó
• kubelet
• kube-proxy

Fazer upgrade manual de um pool de nós

É possível fazer upgrade manual de uma versão do pool de nós para igualá-la à versão do plano de controle ou a uma versão anterior que ainda esteja disponível e seja compatível com o plano de controle. É possível fazer upgrade manual de vários pools de nós em paralelo, enquanto o GKE atualiza automaticamente apenas um pool de nós por vez.

Quando você faz upgrade manual de um pool de nós, o GKE remove todos os rótulos adicionados a nós individuais usando kubectl. Para evitar isso, aplique rótulos aos pools de nós

Observação: o upgrade de um pool de nós pode interromper a execução das cargas de trabalho nele. Para evitar que isso aconteça, crie um novo pool de nós com a versão pretendida e migre a carga de trabalho. Após a migração, é possível excluir o antigo pool de nós.

Observação: se você fizer upgrade de um pool de nós que tenha uma Entrada com erro, o grupo da instância não será sincronizado. Para resolver esse problema, primeiro verifique status usando o comando kubectl get ing. Se o grupo de instâncias não estiver sincronizado, aplique novamente o manifesto usado para criar o ingress.

É possível fazer upgrade dos pools de nós manualmente para uma versão compatível com o plano de controle usando o Console do Google Cloud ou a Google Cloud CLI.

gcloud

As variáveis a seguir são usadas nos comandos desta seção:

• CLUSTER_NAME: o nome do cluster do pool de nós a ser atualizado.
• NODE_POOL_NAME: o nome do pool de nós a ser atualizado.
• VERSION: a versão do Kubernetes para que os nós são atualizados. Por exemplo, --cluster-version=1.7.2 ou cluster-version=latest.

Fazer upgrade de um pool de nós:

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME

Para especificar uma versão diferente do GKE nos nós, use a sinalização opcional --cluster-version:

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME \
  --cluster-version VERSION

Para mais informações sobre como especificar versões, consulte Controle de versões.

Para mais informações, consulte a documentação gcloud container clusters upgrade.

Console

Para fazer upgrade de um pool de nós com o console do Google Cloud, siga as etapas a seguir:

1. Acesse a página do Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Ao lado do cluster que você quer editar, clique em Ações e, depois, em Editar.

3. Na página Detalhes do cluster, clique na guia Nós.

4. Na seção Pools de nós, clique no nome do pool de nós que você quer atualizar.

5. Clique em Editar.

6. Em Versão do nó, clique em Alterar.

7. Selecione a versão pretendida na lista suspensa Versão do nó e clique em Alterar.

Observação: talvez leve vários minutos para que a versão do nó seja alterada.

Como fazer downgrade de pools de nós

É possível fazer downgrade de um pool de nós, por exemplo, para reduzir um upgrade mal-sucedido. Analise as limitações antes de fazer downgrade de um pool de nós.

Observação: recomendamos a estratégia de upgrade de nós azul/verde quando você precisa de otimização para mitigar riscos em upgrades de pool de nós que afetam suas cargas de trabalho. Com essa estratégia, é possível reverter um upgrade em andamento para os nós originais se o upgrade não for bem-sucedido.

1. Defina uma exclusão de manutenção para o cluster para evitar que o pool de nós seja atualizado automaticamente pelo GKE após o downgrade.
2. Para fazer downgrade de um pool de nós, especifique uma versão anterior seguindo as instruções para Fazer upgrade manual de um pool de nós.

Como mudar os parâmetros de upgrade imediato

Para saber mais sobre como alterar os parâmetros de upgrade de sobretensão, consulte Configurar upgrades de sobrecarga.

Como verificar o status do upgrade de pool de nós

É possível verificar o status de um upgrade usando gcloud container operations.

Veja uma lista de todas as operações em execução e concluídas no cluster:

gcloud container operations list

Cada operação recebe um código e um tipo, além de horários de início e término, cluster de destino e status. A lista é semelhante ao exemplo a seguir:

NAME                              TYPE                ZONE           TARGET              STATUS_MESSAGE  STATUS  START_TIME                      END_TIME
operation-1505407677851-8039e369  CREATE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT16:47:57.851933021Z  20xx-xx-xxT16:50:52.898305883Z
operation-1505500805136-e7c64af4  UPGRADE_CLUSTER     us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:40:05.136739989Z  20xx-xx-xxT18:41:09.321483832Z
operation-1505500913918-5802c989  DELETE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:41:53.918825764Z  20xx-xx-xxT18:43:48.639506814Z

Para ver mais informações sobre uma operação específica, informe o ID da operação, conforme mostrado no comando a seguir:

gcloud container operations describe OPERATION_ID

Exemplo:

gcloud container operations describe operation-1507325726639-981f0ed6
endTime: '20xx-xx-xxT21:40:05.324124385Z'
name: operation-1507325726639-981f0ed6
operationType: UPGRADE_CLUSTER
selfLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/operations/operation-1507325726639-981f0ed6
startTime: '20xx-xx-xxT21:35:26.639453776Z'
status: DONE
targetLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/clusters/...
zone: us-central1-a

Verificando as configurações de upgrade do pool de nós

É possível ver detalhes sobre a estratégia de upgrade de nós que está sendo usada para os pools de nós usando o comando gcloud container node-pools describe. Para upgrades em azul-verde, o comando também retorna a fase atual do upgrade.

Execute este comando:

gcloud container node-pools describe NODE_POOL_NAME \
--cluster=CLUSTER_NAME

Substitua:

• NODE_POOL_NAME: o nome do pool de nós a ser descrito.
• CLUSTER_NAME: o nome do cluster do pool de nós a ser descrito.

Este comando exibirá as configurações de upgrade atuais. No exemplo a seguir, a saída será exibida se você estiver usando a estratégia de upgrade azul-verde.

upgradeSettings:
  blueGreenSettings:
    nodePoolSoakDuration: 1800s
    standardRolloutPolicy:
      batchNodeCount: 1
      batchSoakDuration: 10s
  strategy: BLUE_GREEN

Se você estiver usando a estratégia de upgrade azul-verde, a saída também incluirá detalhes sobre as configurações de upgrade azul-verde e a fase intermediária atual. O exemplo a seguir mostra como isso pode ser feito:

updateInfo:
  blueGreenInfo:
    blueInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{BLUE_INSTANCE_GROUP_NAME}
    bluePoolDeletionStartTime: {BLUE_POOL_DELETION_TIME}
    greenInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{GREEN_INSTANCE_GROUP_NAME}
    greenPoolVersion: {GREEN_POOL_VERSION}
    phase: DRAINING_BLUE_POOL

Como cancelar um upgrade de pool de nós

Você pode cancelar um upgrade a qualquer momento. Para saber mais sobre o que acontece quando você cancela um upgrade súbito, consulte Cancelar um upgrade súbito. Para saber mais sobre o que acontece quando você cancela um upgrade azul-verde, consulte Cancelar um upgrade azul-verde.

1. Consiga o ID da operação de upgrade:

   gcloud container operations list
   

2. Cancelar o upgrade:

   gcloud container operations cancel OPERATION_ID
   

Consulte a documentação gcloud container operations cancel.

Como retomar um upgrade de pool de nós

É possível retomar um upgrade iniciando-o manualmente novamente, especificando a versão de destino do upgrade original.

Por exemplo, se você pausou um upgrade em andamento para a versão 1.23.1-gke.100, é possível retomar o upgrade cancelado iniciando o mesmo upgrade novamente no pool de nós, segmentando a versão 1.23.1-gke.100.

Para saber mais sobre o que acontece quando você retoma um upgrade, consulte Retomar um upgrade súbito e Upgrade azul-verde.

Para retomar um upgrade, use o seguinte comando:

    gcloud container clusters upgrade CLUSTER_NAME \
      --node-pool=NODE_POOL_NAME \
      --cluster-version VERSION

Substitua:

• NODE_POOL_NAME: o nome do pool de nós em que você quer retomar o upgrade dele.
• CLUSTER_NAME: o nome do cluster do pool de nós em que você quer retomar o upgrade.
• VERSION: a versão de destino do upgrade do pool de nós cancelado.

Para mais informações, consulte a documentação gcloud container clusters upgrade.

Como reverter um upgrade de pool de nós

É possível reverter um pool de nós para fazer downgrade dos nós atualizados para o estado original antes do início do upgrade.

Use o comando rollback se um upgrade em andamento tiver sido cancelado, tiver ocorrido falha no upgrade ou ele estiver incompleto devido a uma janela de manutenção tempo limite. Como alternativa, se você quiser especificar a versão, siga as instruções para fazer downgrade do pool de nós.

Observação: Não é possível revertê-los depois da atualização. Será necessário fazer downgrade do pool de nós se você precisar que os nós estejam na versão anterior.

Para saber mais sobre o que acontece quando você reverte um upgrade de pool de nós, consulte Reverter um upgrade súbito ou Reverter um upgrade azul-verde.

Para reverter um upgrade, execute o seguinte comando:

gcloud container node-pools rollback NODE_POOL_NAME \
  --cluster CLUSTER_NAME

Substitua:

• NODE_POOL_NAME: o nome do pool de nós para reverter o upgrade do pool de nós.
• CLUSTER_NAME: o nome do cluster do pool de nós para onde reverter o upgrade.

Consulte a documentação gcloud container node-pools rollback.

Como concluir um upgrade do pool de nós

Aviso: só é possível usar o comando complete-upgrade com upgrades azul-verde.

Se você estiver usando a estratégia de upgrade azul-verde, poderá concluir um upgrade do pool de nós durante a fase de imersão, pulando o restante do tempo de imersão.

Para saber como fazer um upgrade do pool de nós, consulte Concluir um upgrade do pool de nós.

Para concluir um upgrade usando a estratégia azul-verde, execute o seguinte comando:

gcloud container node-pools complete-upgrade NODE_POOL_NAME \
  --cluster CLUSTER_NAME

Substitua:

• NODE_POOL_NAME: o nome do pool de nós em que você quer concluir o upgrade.
• CLUSTER_NAME: o nome do cluster do pool de nós para o qual você quer concluir o upgrade.

Consulte a documentação gcloud container node-pools complete-upgrade.

Problemas conhecidos

Se você tiver objetos PodDisruptionBudget configurados que não podem permitir outras interrupções, o upgrade dos nós poderá falhar no upgrade para a versão do plano de controle após várias tentativas. Para evitar essa falha, recomendamos que você escalone verticalmente Deployment ou HorizontalPodAutoscaler para permitir que o nó seja drenado enquanto respeita a configuração PodDisruptionBudget.

Para ver todos os objetos PodDisruptionBudget que não permitem interrupções:

kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'

Embora os upgrades automáticos possam encontrar o problema, o processo de upgrade automático força os nós a fazer upgrade. No entanto, o upgrade leva uma hora extra para cada nó no namespace istio-system que viola o PodDisruptionBudget.

Solução de problemas

Uso de CPU dos nós acima do esperado

Talvez você encontre um problema em que alguns nós estão usando um uso de CPU maior do que o esperado dos pods em execução.

Isso pode ocorrer se o cluster ou os nós não estiverem executando uma versão compatível. Revise as Notas de lançamento para garantir que as versões usadas estejam disponíveis e sejam compatíveis. Também é possível executar o seguinte comando para listar todas as versões compatíveis de cluster e nó:

gcloud container get-server-config

A seguir

• Saiba mais sobre a arquitetura de cluster.
• Saiba mais sobre os canais de lançamento.