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.
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.
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
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.
Console
Para atualizar manualmente o plano de controle do cluster, siga estas etapas:
Acesse a página do Google Kubernetes Engine no console do Google Cloud.
Clique no nome do cluster que você quer.
Em Princípios básicos do cluster, clique em edit Upgrade disponível ao lado de Versão.
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
- 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.
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
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.
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:
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
É 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.2oucluster-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:
Acesse a página do Google Kubernetes Engine no console do Google Cloud.
Ao lado do cluster que você quer editar, clique em more_vert Ações e, depois, em edit Editar.
Na página Detalhes do cluster, clique na guia Nós.
Na seção Pools de nós, clique no nome do pool de nós que você quer atualizar.
Clique em edit Editar.
Em Versão do nó, clique em Alterar.
Selecione a versão pretendida na lista suspensa Versão do nó e clique em Alterar.
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.
- 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.
- 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.
Consiga o ID da operação de upgrade:
gcloud container operations listCancelar 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 um upgrade falhar ou se você pausar um upgrade em andamento, será possível retomar o upgrade cancelado iniciando o mesmo upgrade novamente no pool de nós, especificando a versão de destino da operação inicial de upgrade.
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.
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
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
Retomar ou reverter um upgrade de pool de nós incompleto
Se o GKE não concluir um upgrade do pool de nós e os nós forem parcialmente atualizados para a nova versão, você poderá retomar ou reverter o upgrade. Isso é relevante para upgrades de pool de nós que usam a estratégia de upgrade de nós, upgrades súbitos ou upgrades azuis-verdes.
Um pool de nós pode ser atualizado parcialmente por um dos seguintes motivos:
- Você cancelou o upgrade do pool de nós.
- O upgrade falhou devido a um problema imprevisto.
- O upgrade está incompleto devido ao tempo limite de uma janela de manutenção.
Siga as instruções para retomar ou reverter o upgrade para que todos os nós no pool de nós executem uma versão consistente. Se você não fizer nada, o GKE tentará atualizar o pool de nós novamente quando houver disponibilidade de manutenção.
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.