Fazer upgrade das regras de versão

Entender como a versão atual e a versão de destino afetam o upgrade do cluster ajuda a verificar o desvio de versão, a ordem de upgrade e os requisitos do SO antes de começar.

Informações de upgrade específicas da versão

A tabela a seguir descreve as informações de upgrade específicas da versão. Depois da tabela, você encontra detalhes sobre versões específicas. As versões são ordenadas da mais recente para a mais antiga. Encontre a versão para a qual você está fazendo upgrade para ver os detalhes e as regras específicos que se aplicam ao cluster.

Versão Faça upgrade primeiro Versões do plano de controle (CP) Versões do pool de nós de trabalho Status do cluster avançado Recursos legados compatíveis? Imagens do SO padrão e obrigatórias Comportamento de upgrade de nós do Kubeception Pacote cert-manager
1.36 Cluster de administrador 1.36, 1.35, 1.34 1.36, 1.35, 1.34 Obrigatório Nenhum ubuntu_cgv2, cos_cgv2 Sem suporte Em pacote
1.35 Cluster de administrador 1.35, 1.34, 1.33 1.35, 1.34, 1.33 Obrigatório Nenhum ubuntu_cgv2, cos_cgv2 obrigatório (cgroup v1 descartado) Sem suporte Em pacote
1.34 Cluster de administrador 1.34, 1.33, 1.32 1.34, 1.33, 1.32 Obrigatório (sem desativação; conversão automática não avançada) Nenhum ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Sem suporte Em pacote
1.33 Cluster de administrador 1.33, 1.32, 1.31 1.33, 1.32, 1.31 Padrão (conversão automática) (desativação apenas para 1.32 a 1.33) Nenhum ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Sem suporte Pacote para clusters avançados
1.32 Cluster de administrador 1.32, 1.31, 1.30 1.32, 1.31, 1.30 GA (com suporte para upgrades, upgrades de nós separados e ignorados) Nenhum ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Sem suporte (é necessário migrar para o Controlplane V2) Pacote para clusters avançados
1.31 Cluster de administrador 1.31, 1.30, 1.29 1.31, 1.30, 1.29 Pré-lançamento (sem upgrade para 1.32; sem upgrades de nó separados ou ignorados) Sim (Seesaw, F5, Kubeception, não HA); a migração para os recursos recomendados é altamente recomendada; o Dataplane V2 é obrigatório ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Nós de administrador atualizados com o administrador; nós do CP de usuário atualizados com o cluster de usuário Não agrupado
1.30 Cluster de usuário 1,30 1.30, 1.29, 1.28 Indisponível Sim (Seesaw, F5, Kubeception, sem alta disponibilidade). É altamente recomendável migrar para os recursos recomendados. ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Nós de CP e de admin atualizados durante o upgrade do cluster de admin Não agrupado
1.29 Cluster de usuário 1.29, 1.30 1.29, 1.28, 1.16 Indisponível Sim (Seesaw, F5, Kubeception, sem alta disponibilidade) ubuntu_cgv2 (padrão), cos_cgv2, ubuntu_containerd, cos Nós de CP e de admin atualizados durante o upgrade do cluster de admin Não agrupado
1.28 Cluster de usuário 1.28, 1.29, 1.30 1.28, 1.16, 1.15 Indisponível Sim (Seesaw, F5, Kubeception, sem alta disponibilidade) ubuntu_containerd (padrão), cos, ubuntu_cgv2, cos_cgv2 Nós de CP e de admin atualizados durante o upgrade do cluster de admin Não agrupado

Para todas as versões, é necessário fazer upgrade das versões do pool de nós do balanceador de carga (pools de nós com enableLoadBalancer: true) ao mesmo tempo e para a mesma versão do plano de controle do cluster de usuário.

Informações de upgrade por versão de lançamento

Encontre a seção da versão para a qual você está fazendo upgrade para ver informações específicas necessárias para fazer upgrade para essa versão.

Versão 1.36

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.36 pode gerenciar clusters de usuário nas versões 1.36, 1.35 e 1.34.
  • Versões do plano de controle do cluster de usuário: 1.36, 1.35 ou 1.34.
  • Versões do pool de nós de trabalho: 1.36, 1.35 ou 1.34.

Status do cluster avançado: os clusters avançados são obrigatórios.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: não. Bloqueia o upgrade.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2. O padrão de osImageType para novas configurações é ubuntu_cgv2.

Comportamento de upgrade de nó do Kubeception: não compatível. Bloqueia o upgrade.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. As versões compatíveis são 1.36, 1.37 e 1.38.
  • Terraform: compatível se você tiver criado o cluster de usuário usando o Terraform.
  • Google Cloud console: compatível com upgrades de cluster de usuário.
  • Google Cloud CLI: compatível com upgrades de cluster de usuário.

Outros requisitos:

  • É possível executar upgrades de cluster de administrador de forma assíncrona com gkectl upgrade admin --async.

Versão 1.35

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.35 pode gerenciar clusters de usuário nas versões 1.35, 1.34 e 1.33.
  • Versões do plano de controle do cluster de usuário: 1.35, 1.34 ou 1.33.
  • Versões do pool de nós de trabalho: 1.35, 1.34 ou 1.33.

Status do cluster avançado: os clusters avançados são obrigatórios.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: não. Bloqueia o upgrade.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2 obrigatório (cgroup v1 removido). O osImageType padrão para novas configurações é ubuntu_cgv2. É necessário migrar os clusters para o cgroup v2 antes de fazer upgrade.

Comportamento de upgrade de nó do Kubeception: não compatível. Bloqueia o upgrade.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. As versões compatíveis são 1.35, 1.36 e 1.37.
  • Terraform: compatível se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades de cluster de usuário.
  • CLI gcloud: compatível com upgrades de cluster de usuário.

Outros requisitos:

  • É possível executar upgrades de cluster de administrador de forma assíncrona com gkectl upgrade admin --async.

Versão 1.34

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.34 pode gerenciar clusters de usuário nas versões 1.34, 1.33 e 1.32.
  • Versões do plano de controle do cluster de usuário: 1.34, 1.33 ou 1.32.

  • Versões do pool de nós de trabalho: 1.34, 1.33 ou 1.32.

Status do cluster avançado: os clusters avançados são obrigatórios.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: não. Bloqueia o upgrade.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Comportamento de upgrade de nó do Kubeception: não compatível. Bloqueia o upgrade.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. Necessário para converter clusters não avançados em clusters avançados (obrigatório na versão 1.34; a versão binária de gkectl precisa corresponder exatamente à versão de lançamento de destino). As versões compatíveis são 1.34, 1.35 e 1.36.
  • Terraform: compatível se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades avançados de clusters de usuário.
  • CLI gcloud: compatível com upgrades avançados de clusters de usuário.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.34:

  • Os clusters não avançados são convertidos automaticamente em clusters avançados quando você faz upgrade para a versão 1.34. Para informações sobre as regras específicas de upgrades de clusters não avançados para avançados, consulte Atualizar ou fazer upgrade de um cluster para um cluster avançado.

  • O cert-manager em pacote é obrigatório e foi atualizado para a versão 1.19, substituindo as instalações personalizadas preexistentes do cert-manager. Para mais informações sobre upgrades para o cert-manager em pacote, consulte Usar o cert-manager em pacote.

  • O ambiente de execução do contêiner do nó foi atualizado para o containerd 2.0. Esse processo pode ter os seguintes impactos:

    • O containerd 2.0 não é compatível com imagens legadas do Docker Image Manifest v2 ou do Schema 1. Verifique se as cargas de trabalho extraem imagens de contêiner usando o esquema 2 do Docker ou um formato compatível com OCI antes de fazer upgrade para a versão 1.34.
    • A configuração do espelho do registro é migrada para o formato hosts.toml no containerd 2.0. Se você gerencia configurações de espelhamento personalizadas ou endpoints de registro com isolamento físico diretamente nos nós, verifique se a configuração está alinhada com hosts.toml.
    • Se você usa DaemonSets ou scripts personalizados que corrigem /etc/containerd/config.toml, verifique se eles não usam opções de configuração descontinuadas do containerd v1, o que pode causar falhas de inicialização do containerd com o containerd 2.0.

  • O valor padrão do campo nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate mudou na versão 1.34.300. Se você quiser upgrades sequenciais de pool de nós nas versões 1.34.300+, defina nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate: 1 no arquivo de configuração do cluster de usuário:

    • Para as versões 1.34.0 a 1.34.200, nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate assume como padrão 1, que atualiza um pool de nós por vez sequencialmente.
    • Para as versões 1.34.300+, nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate assume como padrão 0, que atualiza todos os pools de nós simultaneamente.

    Para mais informações, consulte Configurar a política de atualização do pool de nós.

  • As verificações de simulação de upgrade validam ativamente todas as configurações de PodDisruptionBudget (PDB) no cluster. Antes de fazer upgrade, verifique se as cargas de trabalho não têm PDBs excessivamente restritivos (por exemplo, maxUnavailable: 0 ou minAvailable correspondentes ao total de réplicas) que bloqueiam a drenagem de nós ou as verificações de simulação podem falhar.

  • Se um upgrade for interrompido, faça upgrade diretamente para a versão 1.34.300-gke.59 ou mais recente. Essa versão impede que o cluster de inicialização seja excluído se você precisar executar novamente gkectl upgrade admin após uma falha. Para mais informações, consulte A nova execução de gkectl upgrade admin exclui o cluster de inicialização.

  • É possível executar upgrades de cluster de administrador de forma assíncrona com gkectl upgrade admin --async para clusters avançados, exceto ao converter de um cluster não avançado para um avançado.

Versão 1.33

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.33 pode gerenciar clusters de usuário nas versões 1.33, 1.32 e 1.31.
  • Versões do plano de controle do cluster de usuário: 1.33, 1.32 ou 1.31.

  • Versões do pool de nós de trabalho: 1.33, 1.32 ou 1.31.

Status do cluster avançado: os clusters avançados são o tipo de cluster padrão e são convertidos automaticamente. Recusa permitida. Para mais informações, consulte Fazer upgrade e manter clusters não avançados. Se você definir enableAdvancedCluster como false, a criação do cluster vai falhar.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: não. Bloqueia o upgrade.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Comportamento de upgrade de nó do Kubeception: não compatível. Bloqueia o upgrade.

Ferramentas de upgrade:

  • gkectl: obrigatório para converter clusters não avançados em clusters avançados. A versão binária de gkectl precisa corresponder exatamente à versão de lançamento de destino. Obrigatório para clusters de administrador. As versões compatíveis são 1.33, 1.34 e 1.35.
  • Terraform: compatível se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades avançados de clusters de usuário.
  • CLI gcloud: compatível com upgrades avançados de clusters de usuário.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.33:

  • Os upgrades da versão 1.32 para a 1.33 convertem automaticamente clusters não avançados em clusters avançados por padrão. É possível manter os clusters não avançados. Para mais informações sobre como manter os clusters não avançados, consulte Fazer upgrade e manter clusters não avançados.

  • Os clusters avançados instalam e agrupam automaticamente o cert-manager v1.18, substituindo as instalações personalizadas preexistentes do cert-manager. Para mais informações sobre upgrades para o cert-manager em pacote, consulte Usar o cert-manager em pacote.

  • Se você fizer upgrade para clusters avançados nesta versão, a versão binária do gkectl precisará corresponder exatamente à versão de lançamento de destino ao converter de clusters não avançados para avançados. Esse requisito só se aplica durante o upgrade para um cluster avançado. Para todos os outros upgrades no cluster avançado, as regras de desvio de versão padrão estão em vigor.

  • Se um upgrade for interrompido, faça upgrade diretamente para a versão 1.33.700-gke.71 ou mais recente. Essa versão impede que o cluster de inicialização seja excluído se você precisar executar novamente gkectl upgrade admin após uma falha.

  • É possível executar upgrades de clusters de administrador de forma assíncrona com gkectl upgrade admin --async para clusters avançados e clusters de alta disponibilidade não avançados se todos os clusters de usuário executarem o Controlplane V2. Não é possível usar a flag --async ao converter de um cluster não avançado para um avançado.

Versão 1.32

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.32 pode gerenciar clusters de usuário nas versões 1.32, 1.31 e 1.30.
  • Versões do plano de controle do cluster de usuário: 1.32, 1.31 ou 1.30.

  • Versões do pool de nós de trabalho: 1.32, 1.31 ou 1.30.

Status avançado do cluster: compatível.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: não. Bloqueia o upgrade.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Comportamento de upgrade de nó do Kubeception: não compatível. Bloqueia o upgrade. É necessário migrar para o Controlplane V2.

Ferramentas de upgrade:

  • gkectl: obrigatório para converter clusters não avançados em clusters avançados. A versão binária de gkectl precisa corresponder exatamente à versão de lançamento de destino. Obrigatório para clusters de administrador. As versões compatíveis são 1.32, 1.33 e 1.34.
  • Terraform: compatível se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades avançados de clusters de usuário.
  • CLI gcloud: compatível com upgrades avançados de clusters de usuário.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.32:

  • Esta é a primeira versão que permite um upgrade opcional para um cluster avançado de GA totalmente compatível. Você pode:

    • Fazer upgrade para um cluster não avançado e manter o cluster não avançado. Se você escolher essa opção, poderá fazer o seguinte, a partir desta versão:

      • Faça upgrade do plano de controle do cluster de usuário e dos pools de nós de trabalho separadamente. Os pools de nós de trabalho podem estar até duas versões secundárias atrás do plano de controle.
      • Execute o upgrade de forma assíncrona para clusters de administrador e de usuário.

    • Faça upgrade para um cluster não avançado e converta-o em um cluster avançado. Se você escolher essa opção, poderá fazer o seguinte, a partir desta versão:

      • Faça upgrade do plano de controle do cluster de usuário e dos pools de nós de trabalho separadamente ao fazer upgrade do cluster não avançado, mas não ao converter para um cluster avançado. Os pools de nós de trabalho podem estar até duas versões secundárias atrás do plano de controle.
      • Execute o upgrade de forma assíncrona para clusters de administrador e de usuário ao fazer upgrade do cluster não avançado.
      • Ao converter para o cluster avançado, faça upgrade para a versão de lançamento 1.32.1000-gke.57 ou mais recente, porque ela incorpora uma correção para um problema conhecido que impede a exclusão do cluster de inicialização.

    • Fazer upgrade para um cluster avançado diretamente. Se você escolher essa opção, o seguinte será aplicado, a partir desta versão:

      • É preciso fazer upgrade do plano de controle e de todos os pools de nós juntos.
      • É possível executar o upgrade de forma assíncrona para clusters de usuário, mas não para clusters de administrador.
      • Faça upgrade para a versão de lançamento 1.32.1000-gke.57 ou mais recente, porque ela incorpora uma correção para um problema conhecido que impede a exclusão do cluster de inicialização.

  • Os seguintes recursos legados não são mais compatíveis a partir desta versão. Para mais informações, consulte Recursos legados:

    • Dataplane V1 (Calico). Faça upgrade para o Dataplane V2 antes de fazer upgrade para a versão 1.32.
    • Seesaw. Faça upgrade para um balanceador de carga alternativo antes de fazer upgrade para a versão 1.32.
    • F5 BIG-IP integrado. Faça upgrade para um balanceador de carga alternativo antes de fazer upgrade para a versão 1.32.
    • Kubeception. Faça upgrade para um cluster que não seja do Kubeception antes de fazer upgrade para a versão 1.32.
    • Clusters de administrador sem alta disponibilidade. Faça upgrade para um cluster de administrador de alta disponibilidade antes de fazer upgrade para a versão 1.32.

  • A versão binária do gkectl precisa corresponder exatamente à versão de lançamento de destino ao converter clusters não avançados em avançados. Esse requisito só se aplica durante o upgrade para um cluster avançado. Para todos os outros upgrades no cluster avançado, as regras de desvio de versão padrão estão em vigor.

  • Se um upgrade for interrompido, faça upgrade diretamente para a versão 1.32.1000-gke.57 ou mais recente. Essa versão impede que o cluster de inicialização seja excluído se você precisar executar novamente gkectl upgrade admin após uma falha.

  • Na versão 1.32 e mais recentes, é possível executar upgrades de clusters de administrador de forma assíncrona com gkectl upgrade admin --async para clusters avançados e clusters de alta disponibilidade não avançados se todos os clusters de usuário executarem o Controlplane V2. Não é possível usar a flag --async ao converter de um cluster não avançado para um avançado.

Versão 1.31

Fazer upgrade primeiro: cluster de administrador

Regras de distorção de versão:

  • O cluster de administrador na versão 1.31 pode gerenciar clusters de usuário nas versões 1.31, 1.30 e 1.29.
  • Versões do plano de controle do cluster de usuário: 1.31, 1.30 ou 1.29.
  • Versões do pool de nós de trabalho: 1.31, 1.30 ou 1.29. Não compatível com clusters avançados 1.31.
  • Para fazer upgrade da versão 1.29/1.30 para a 1.31, é necessário fazer upgrade de todos os clusters para a versão 1.30 antes de fazer upgrade do cluster de administrador para a 1.31.

Status do cluster avançado: somente pré-lançamento. Não é possível fazer upgrade para versões mais recentes.

Pular upgrades de nós: compatível.

Recursos legados compatíveis: Dataplane V2 obrigatório; Kubeception, Seesaw e F5 ainda são compatíveis.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Comportamento de upgrade de nó do Kubeception: nós de administrador atualizados com o cluster de administrador; nós do plano de controle de usuário atualizados com o cluster de usuário.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador, clusters não avançados e clusters avançados (pré-lançamento, para esta versão). As versões compatíveis são 1.31, 1.32 e 1.33.
  • Terraform: compatível com clusters de usuário registrados se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades de clusters de usuário registrados.
  • CLI gcloud: compatível com upgrades de clusters de usuário registrados.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.31:

  • Esta versão introduziu clusters avançados no modo de pré-lançamento. Não é possível migrar clusters não avançados para clusters avançados nesta versão. É possível criar novos clusters como clusters avançados, mas não é possível fazer upgrade desses clusters avançados da versão de pré-lançamento para uma versão mais recente. Não recomendamos a criação de clusters avançados nesta versão. Para mais informações sobre as fases de lançamento de produtos, como pré-lançamento, consulte Fases de lançamento de produtos.

  • Na versão 1.31 e mais recentes, a arquitetura de upgrades mudou para um modelo em que o cluster de administrador precisa ser mais recente ou igual aos clusters de usuário. Anteriormente, os clusters de usuário podiam estar até duas versões secundárias à frente do cluster de administrador.

  • É preciso fazer upgrade do cluster de administrador antes de fazer upgrade dos clusters de usuário gerenciados por ele. Os clusters de administrador podem gerenciar clusters de usuário com a mesma versão secundária ou até duas versões secundárias anteriores. Por exemplo, um cluster de administrador na versão 1.31 pode gerenciar clusters de usuário nas versões 1.31, 1.30 e 1.29.

  • Para fazer upgrade da versão 1.29 para a 1.31, é necessário preparar o pacote 1.30 como uma etapa intermediária. É necessário fazer o download dos pacotes 1.30 e 1.31 na estação de trabalho do administrador para fazer upgrade para a versão 1.31. Para fazer um upgrade de versão pulada da 1.29 para a 1.31, faça o seguinte:

    1. Faça upgrade apenas do plano de controle do cluster de usuário da versão 1.29 para a 1.30 (deixando os pools de nós de trabalho na versão 1.29).
    2. Faça upgrade do cluster de administrador da versão 1.29 para a 1.30.
    3. Faça upgrade do cluster de administrador da versão 1.30 para a versão de destino 1.31.
    4. Faça upgrade do plano de controle do cluster de usuário e dos pools de nós de trabalho juntos para a versão 1.31.

  • Se você usa o Kubeception, os nós do cluster de administrador são atualizados durante o upgrade do cluster de administrador, e os nós do plano de controle do cluster de usuário são atualizados durante o upgrade do cluster de usuário.

  • Para fazer upgrade para a versão 1.31, é necessário ativar o Dataplane V2. Para evitar conflitos de política de rede e quedas de tráfego durante a migração da CNI, salve e exclua manualmente todos os objetos NetworkPolicy e restaure-os após o upgrade. Para fazer a transição para o Dataplane V2, faça o seguinte:

    1. Exporte e salve todas as políticas de rede personalizadas:

      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get networkpolicy -A -o wide \
    --field-selector metadata.namespace!=kube-system
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get networkpolicy POLICY_NAME \
    -n NAMESPACE -o yaml > policy.yaml

      Substitua:

      • USER_CLUSTER_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de usuário.
      • POLICY_NAME: o nome do objeto NetworkPolicy.
      • NAMESPACE: o namespace do objeto NetworkPolicy.

    2. Exclua as políticas de rede do cluster:

      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    delete networkpolicy POLICY_NAME \
    -n NAMESPACE

    3. Defina enableDataplaneV2: true no arquivo de configuração do cluster de usuário e faça o upgrade para a versão 1.31.

    4. Aplique as políticas salvas após a conclusão do upgrade para a versão 1.31 para que o Cilium as compile de forma limpa no filtro de pacote Berkeley estendido (eBPF):

      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    apply -f policy.yaml

  • Se você tiver clusters de administrador de alta disponibilidade e todos os clusters de usuário executarem o Controlplane V2, será possível executar o upgrade de forma assíncrona com o comando gkectl upgrade admin --async.

  • O Dataplane V2 é obrigatório para todos os clusters de usuário. Antes de fazer upgrade de um cluster de usuário para a versão 1.31, siga as etapas em Ativar o Dataplane V2.

  • Os recursos legados não são compatíveis com a versão 1.32. É possível substituí-los nas versões 1.30 e 1.31 para evitar problemas ao fazer upgrade para a versão 1.32.

Versão 1.30

Fazer upgrade primeiro: cluster de usuário

Regras de distorção de versão:

  • O cluster de usuário na versão 1.30 pode ser gerenciado por um cluster de administrador na versão 1.30, 1.29 ou 1.28.
  • O cluster de administrador na versão 1.30 só pode gerenciar clusters de usuário na versão 1.30. Todos os clusters de usuário e o cluster de administrador precisam chegar à versão 1.30 antes de fazer upgrade do cluster de administrador para a versão 1.31. Além disso, é necessário fazer upgrade do cluster de administrador para a versão 1.31 antes que qualquer cluster de usuário possa fazer upgrade para a versão 1.31.
  • Versões do plano de controle do cluster de usuário: 1.30.
  • Versões do pool de nós de trabalho: 1.30, 1.29 ou 1.28.

Status avançado do cluster: não disponível.

Pular upgrades de nós: compatível.

Recursos legados: compatíveis. A migração para os recursos recomendados é altamente recomendada.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. As versões compatíveis são 1.30, 1.31 e 1.32.
  • Terraform: compatível com clusters de usuário inscritos se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades de clusters de usuário registrados.
  • CLI gcloud: compatível com upgrades de clusters de usuário registrados.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.30:

  • Para esta versão e todas as anteriores, é necessário migrar todos os clusters de usuário antes de fazer upgrade do cluster de administrador de gerenciamento. O cluster de administrador precisa estar na mesma versão secundária ou em uma versão anterior à de qualquer cluster de usuário gerenciado.

  • Se você usar o Kubeception, o seguinte vai acontecer durante um upgrade:

    1. Faça upgrade do cluster de usuário. Como o plano de controle do usuário fica dentro do cluster de administrador, a execução de gkectl upgrade cluster só faz upgrade dos pools de nós de trabalho.
    2. Faça upgrade do cluster de administrador. O upgrade do cluster de admin atualiza os nós de admin e todos os planos de controle do cluster de usuário ao mesmo tempo.

  • Se você tiver o Controlplane V2, o seguinte vai acontecer durante o upgrade:

    1. Faça upgrade do cluster de usuário. Isso faz upgrade do plano de controle e dos pools de nós de trabalho.
    2. Faça upgrade do cluster de administrador. Isso faz upgrade dos nós de administrador.

  • Ao criar um novo cluster de usuário, defina o campo enableControlplaneV2 como true, que é o padrão, a partir desta versão. Se você definir o campo enableControlplaneV2 como false, o gkectl vai rejeitar o arquivo e não vai criar o cluster.

  • Se você tiver clusters de administrador de alta disponibilidade e todos os clusters de usuário executarem o Controlplane V2, será possível executar o upgrade de forma assíncrona com o comando gkectl upgrade admin --async.

  • Os recursos legados não são compatíveis com a versão 1.32. É possível substituí-los nas versões 1.30 e 1.31 para evitar problemas ao fazer upgrade para a versão 1.32.

Versão 1.29

Fazer upgrade primeiro: cluster de usuário

Regras de distorção de versão:

  • O cluster de usuário na versão 1.29 pode ser gerenciado por um cluster de administrador na versão 1.29, 1.28 ou 1.16.
  • O cluster de administrador na versão 1.29 pode gerenciar clusters de usuário nas versões 1.29 e 1.30. Um cluster de administrador na versão 1.29 não pode gerenciar clusters de usuário na versão 1.31 porque todos os clusters precisam primeiro chegar à versão 1.30, e o cluster de administrador precisa ser atualizado para a versão 1.31 antes que qualquer cluster de usuário possa ser atualizado para a versão 1.31.
  • Versões do plano de controle do cluster de usuário: 1.29 ou 1.30, que é até uma versão secundária mais recente.
  • Versões do pool de nós de trabalho: 1.29, 1.28 ou 1.16.

Status avançado do cluster: não disponível.

Pular upgrades de nós: compatível.

Recursos legados: compatíveis.

Imagens do SO padrão e obrigatórias: ubuntu_cgv2, cos_cgv2, ubuntu_containerd, cos. O osImageType padrão é ubuntu_cgv2.

Comportamento de upgrade de nós do Kubeception: o plano de controle e os nós de administrador são atualizados durante o upgrade do cluster de administrador.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. As versões compatíveis são 1.29, 1.30 e 1.31.
  • Terraform: compatível com clusters de usuário inscritos se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades de clusters de usuário registrados.
  • CLI gcloud: compatível com upgrades de clusters de usuário registrados.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.29:

  • Os nós de trabalho podem estar até duas versões secundárias atrás do plano de controle (n+2).
  • É possível pular uma versão secundária ao fazer upgrade de pools de nós de trabalho. Por exemplo, é possível fazer upgrade de um pool de nós de trabalho da versão 1.28 para a 1.30.
  • As verificações de simulação são executadas como pods dentro do cluster de administrador ou de um cluster de inicialização temporário, em vez de na estação de trabalho do administrador.
  • A partir desta versão, é possível executar uma verificação de simulação sem fazer upgrade do cluster usando gkectl upgrade cluster --dry-run.
  • Se você tiver clusters de administrador de alta disponibilidade e todos os clusters de usuário executarem o Controlplane V2, será possível executar o upgrade de forma assíncrona com o comando gkectl upgrade admin --async.

Versão 1.28

Fazer upgrade primeiro: cluster de usuário

Regras de distorção de versão:

  • O cluster de usuário na versão 1.28 pode ser gerenciado por um cluster de administrador na versão 1.28, 1.16 ou 1.15.
  • O cluster de administrador na versão 1.28 pode gerenciar clusters de usuário nas versões 1.28, 1.29 e 1.30.
  • Versões do plano de controle do cluster de usuário: 1.28, 1.29 ou 1.30, que é até duas versões secundárias mais recentes.
  • Versões do pool de nós de trabalho: 1.28, 1.16 ou 1.15, que é até duas versões secundárias anteriores.

Status avançado do cluster: não disponível.

Pular upgrades de nós: compatível.

Recursos legados: compatíveis.

Imagens do SO padrão e obrigatórias: ubuntu_containerd, cos, ubuntu_cgv2, cos_cgv2. O osImageType padrão é ubuntu_containerd.

Comportamento de upgrade de nós do Kubeception: o plano de controle e os nós de administrador são atualizados durante o upgrade do cluster de administrador.

Ferramentas de upgrade:

  • gkectl: obrigatório para clusters de administrador. As versões compatíveis são 1.28, 1.29 e 1.30.
  • Terraform: compatível com clusters de usuário inscritos se você tiver criado o cluster de usuário usando o Terraform.
  • console: compatível com upgrades de clusters de usuário registrados.
  • CLI gcloud: compatível com upgrades de clusters de usuário registrados.

Outros requisitos:

Os seguintes requisitos adicionais se aplicam aos upgrades para a versão 1.28:

  • É necessário ativar kubernetesmetadata.googleapis.com e conceder roles/kubernetesmetadata.publisher à conta de serviço de monitoramento de geração de registros. Caso contrário, as verificações de simulação podem falhar ou você pode ver erros 403 PERMISSION_DENIED. Ative a API e conceda o papel à conta de serviço de monitoramento de registros:

    gcloud services enable kubernetesmetadata.googleapis.com
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:LOGGING_SA" \
    --role="roles/kubernetesmetadata.publisher"

    Substitua:

    • PROJECT_ID: o ID do projeto host da frota em que o cluster de usuário é membro.
    • LOGGING_SA: o endereço de e-mail da sua conta de serviço de geração de registros e monitoramento.

  • Embora seja tecnicamente possível pular versões durante um upgrade de pool de nós, esse recurso foi introduzido como um recurso em fase de pré-lançamento e não é recomendado para esta versão. Para mais informações sobre as fases de lançamento de produtos, como pré-lançamento, consulte Fases de lançamento de produtos.

  • Os pools de nós com um balanceador de carga em pacote precisam corresponder exatamente à versão do cluster.

  • É possível fazer upgrade de vários nós ao mesmo tempo definindo o campo nodePools[i].updateStrategy.rollingUpdate.maxSurge. O cluster do vSphere precisa ter CPU, RAM e endereços IP disponíveis suficientes para acomodar as VMs de aumento extra durante o upgrade:

    • Defina maxSurge: 1 (padrão) para fazer upgrade de um nó por vez (esvaziar, substituir, verificar e repetir).
    • Defina maxSurge: N (em que N > 1) para provisionar e drenar até N nós de trabalho ao mesmo tempo (por exemplo, maxSurge: 3 faz upgrade de 3 nós de trabalho simultaneamente).

  • É necessário ter pelo menos 100 GB de espaço em disco livre na estação de trabalho do administrador para fazer upgrade dela.

  • A versão do gkectl usada para o upgrade pode ser até duas versões secundárias mais recente que o cluster atual. Não é possível usar uma versão secundária anterior.

Versões anteriores à 1.28

Os seguintes requisitos adicionais se aplicam a upgrades para versões anteriores à versão 1.28. Não houve versões de lançamento entre 1.16 e 1.28:

Versão 1.16:

  • O desvio de versão entre os clusters de administrador e de usuário e entre o plano de controle e os pools de nós só pode ser de uma versão secundária. Por exemplo, um cluster de administrador na versão 1.15 só pode gerenciar clusters de usuário com as versões 1.15 ou 1.16. Um plano de controle de cluster de usuário atualizado para a versão 1.16 pode gerenciar pools de nós de trabalho que executam a versão 1.15 ou 1.16. Um pool na versão 1.14 precisa ser atualizado para a versão 1.15 antes que o plano de controle possa ser atualizado para a versão 1.16. Para mais informações sobre desvios de versão, consulte Regras de desvio de versão.
  • Os clusters são registrados automaticamente na API GKE On-Prem quando criados ou atualizados para a versão 1.16. Com essa mudança, é possível visualizar, monitorar e fazer upgrade de clusters de usuário usando o console, a CLI gcloud e o Terraform, em vez de apenas o shell da estação de trabalho de administrador.

Versão 1.14:

  • É possível fazer upgrade apenas do plano de controle do cluster de usuário primeiro, para que você não precise drenar e fazer upgrade de todos os pools de nós de trabalho ao mesmo tempo.
  • Durante o upgrade, o sistema inspeciona e atualiza automaticamente os arquivos kubeconfig dos clusters de administrador e de usuário na estação de trabalho, renovando as credenciais automaticamente.

Versão 1.13:

  • Antes dessa versão, era possível ter um cluster de administrador off-line. Esta versão exige que você registre o cluster de administrador no Google Cloud. Para saber como registrar um cluster, consulte Registrar um cluster atual.
  • Para fazer upgrade de um cluster para o software do Google Distributed Cloud apenas para VMware versão 1.13 ou mais recente, primeiro é necessário atualizar todos os pools de nós de cluster de usuário que ainda usam o Docker Engine para containerd.

Usar o cert-manager incluído

Use o cert-manager incluído, que é instalado automaticamente em clusters avançados. Quando você migra de um cluster não avançado para um cluster avançado, o cert-manager integrado substitui automaticamente todas as versões do cert-manager instaladas pelo cliente. Verifique se você não tem configurações ou recursos personalizados essenciais aplicados ao cert-manager atual antes de atualizar ou fazer upgrade para clusters avançados.

Para ver se você aplicou configurações ou recursos personalizados críticos ao cert-manager, faça o seguinte:

  • Suspender as ferramentas de implantação contínua. Se você gerencia o cert-manager usando ferramentas GitOps (como Config Sync, ArgoCD ou Flux), suspenda a sincronização ou remova os manifestos do cert-manager do repositório antes de fazer upgrade. Se um controlador GitOps tentar reconciliar cert-manager com uma versão mais antiga ou um manifesto personalizado enquanto o upgrade do cluster é executado, ele criará um loop de reconciliação que pode interromper o upgrade do cluster.
  • Não desinstale nem exclua manualmente pods, namespaces ou CRDs do cert-manager antes de fazer upgrade. O gkectl gerencia esses upgrades no local.
  • Se você modificou as flags de implantação do cert-manager, os seletores de nós ou os limites de recursos de pods, reverta-os. Os clusters avançados não são compatíveis com argumentos binários personalizados ou substituições no nível da implantação em cert-manager.
  • Se você usa emissores externos especializados, plug-ins de webhook ACME DNS-01 particulares ou webhooks personalizados, verifique se os plug-ins de terceiros são compatíveis com a versão do cert-manager incluída na versão para a qual você está fazendo upgrade.

Para mais informações, consulte Fazer upgrade para o cert-manager em pacote com clusters avançados.

A tabela a seguir lista quais versões de lançamento exigem o cert-manager em pacote:

Versão Status para novos clusters Status dos upgrades de clusters atuais O cert-manager em pacote é obrigatório?
1.34+ Obrigatório Conversão obrigatória (v1.19 em pacote) Obrigatório para todos os clientes. Não é mais possível ter clusters não avançados.
1,33 Padrão para todos os novos clusters Conversão automática para clusters avançados por padrão (v1.18 incluída) Obrigatório para quase todos os clusters, a menos que seja explicitamente desativado com enableAdvancedCluster: false (somente 1.32 → 1.33).
1.32 (GA) Ativado por padrão Conversão opcional para clusters avançados Obrigatório se os clusters avançados estiverem ativados.
1.31 (pré-lançamento) Opcional (enableAdvancedCluster: true) Sem suporte Obrigatório se os clusters avançados estiverem ativados.

Para saber qual versão do cert-manager está incluída em cada versão compatível, consulte Versões do cert-manager incluídas.

Plano de controle V2

Quando o Controlplane V2 está ativado, o plano de controle do cluster de usuário é executado no próprio cluster de usuário. No Controlplane V2, os nós do plano de controle do cluster de usuário são atualizados durante o upgrade do cluster de usuário, e os nós do plano de controle do cluster de administrador são atualizados durante o upgrade do cluster de administrador.

Recursos legados

A tabela a seguir lista os recursos legados que estão bloqueados na versão 1.32 e em versões mais recentes. Se você usa esses recursos, migre para as alternativas recomendadas antes de fazer upgrade para a versão 1.32 ou mais recente.

| Recurso legado (bloqueado na versão 1.32) | Substituir por (recomendado) | Link para as instruções de migração | | --- | --- | --- | | Dataplane V1 (Calico) | Dataplane V2 (Cilium / eBPF) | Migrar para o Dataplane V2| | Kubeception | Controlplane V2 | Migrar para o Controlplane V2 | | Cluster de administrador não HA (1 réplica) | Cluster de administrador de alta disponibilidade (3 réplicas) | Migrar para o cluster de administrador de alta disponibilidade | | Balanceador de carga Seesaw | MetalLB ou ManualLB | Migrar para o MetalLB ou Migrar o tipo de balanceador de carga| | F5 BIG-IP integrado (loadBalancer.kind: "F5BigIP") | ManualLB (pareado com o controlador F5 Big-IP ou CCGI) | Migrar para o ManualLB |

Para detalhes sobre como migrar de recursos legados para recursos recomendados, consulte Planejar a migração de clusters para recursos recomendados.

Comportamento de migração e versão do Kubeception

O Kubeception é um recurso legado que precisa ser migrado para o Controlplane V2 antes de fazer upgrade para a versão 1.32 ou mais recente.

Os upgrades se comportam de maneira diferente para clusters com Kubeception, dependendo da versão:

  • Para 1.28: upgrade do plano de controle e dos nós de administrador durante o upgrade do cluster de administrador
  • Para 1.29: upgrade do plano de controle e dos nós de administrador durante o upgrade do cluster de administrador

  • Para a versão 1.30: upgrade do plano de controle e dos nós de administrador durante o upgrade do cluster de administrador. Se você usar o Kubeception, o seguinte vai acontecer durante um upgrade:

    1. Faça upgrade do cluster de usuário. Como o plano de controle do usuário fica dentro do cluster de administrador, a execução de gkectl upgrade cluster só faz upgrade dos pools de nós de trabalho.
    2. Faça upgrade do cluster de administrador. O upgrade do cluster de admin atualiza os nós de admin e todos os planos de controle do cluster de usuário ao mesmo tempo.

  • Para 1.31: nós de administrador atualizados com o cluster de administrador; nós do plano de controle do usuário atualizados com o cluster de usuário.

  • Para a versão 1.32 e mais recentes: o Kubeception não é compatível. É necessário migrar para o Controlplane V2 antes de fazer upgrade para a versão 1.32 ou mais recente.

    Para detalhes sobre como migrar o Kubeception para o Controlplane V2, consulte Planejar a migração de clusters para recursos recomendados.

Diferença entre desvio de versão e pular uma versão durante o upgrade

O desvio de versão é a diferença permitida em versões secundárias entre um cluster de administrador e os clusters de usuário gerenciados ou a diferença em versões secundárias entre o plano de controle de um cluster de usuário e os pools de nós no cluster de usuário.

O desvio de versão é diferente de pular uma versão secundária ao fazer upgrade.

Só é possível pular uma versão secundária ao fazer upgrade de pools de nós de trabalho, depois de fazer upgrade do plano de controle. Isso se aplica a clusters avançados e não avançados, exceto clusters avançados que executam a versão 1.31 e versões anteriores à 1.28. Por exemplo, se um pool de nós de trabalho estiver na versão 1.29, atualize o plano de controle do cluster de usuário para 1.30 e, em seguida, para 1.31. Depois que o plano de controle estiver na versão 1.31, faça upgrade do pool de nós de trabalho da versão 1.29 para a 1.31 diretamente, sem fazer upgrade para a 1.30. Para mais informações, consulte Pular uma versão ao fazer upgrade de pools de nós.

Para fazer upgrade para uma versão secundária mais recente do que a próxima versão secundária sequencial, faça upgrade para a próxima versão secundária primeiro e, em seguida, faça upgrade para a versão secundária mais recente. Não é possível pular uma versão secundária ao fazer upgrade dos planos de controle de clusters de administrador e de usuário. Por exemplo, se quiser atualizar da versão 1.34.x para a versão 1.36.x, não será possível fazer upgrade diretamente. Primeiro, faça upgrade da versão 1.34.x para a 1.35.x e, em seguida, faça upgrade para a 1.36.x.

O plano de controle de um cluster de usuário pode ter até duas versões secundárias mais recentes que os pools de nós de trabalho no cluster. Por exemplo, se o plano de controle de um cluster de usuário estiver na versão 1.36, os pools de nós de trabalho no cluster poderão ser 1.34, 1.35 ou 1.36.

Quais distorções de versão são permitidas?

Um cluster de administrador pode gerenciar clusters de usuário até duas versões secundárias anteriores. Por exemplo, se um cluster de administrador estiver na versão 1.31, os clusters de usuário gerenciados por esse cluster de administrador poderão estar na 1.29, 1.30 ou 1.31.

Antes da versão 1.31, as seguintes regras de desvio de versão se aplicam:

  • Nas versões 1.28 a 1.30, os clusters de usuário podem ter até duas versões secundárias mais recentes que o cluster de administrador. Por exemplo, se um cluster de administrador estiver na versão 1.15, os clusters de usuário gerenciados por esse cluster de administrador poderão estar na 1.15, 1.16 ou 1.28. Não é possível fazer upgrade de um cluster de usuário 1.28 para 1.29 até que o cluster de administrador seja atualizado para pelo menos 1.16. Como a versão 1.31 muda a ordem de upgrade para exigir que o cluster de administrador seja atualizado primeiro, um cluster de administrador na versão 1.29 ou 1.30 não pode gerenciar clusters de usuário na versão 1.31 ou 1.32. Todos os clusters de usuário e o cluster de administrador precisam chegar à versão 1.30 antes de fazer upgrade do cluster de administrador para a versão 1.31.
  • Nas versões 1.16 e anteriores, os clusters de usuário só podem ter uma versão secundária mais recente que o cluster de administrador. Por exemplo, se um cluster de administrador estiver em 1.15, os clusters do usuário gerenciados pelo cluster de administrador podem estar em 1,15 ou 1,16.

Preciso fazer upgrade de todos os clusters de usuário de uma vez?

Ao fazer upgrade de clusters de usuário, você pode escolher uma das seguintes opções:

  • Faça upgrade de todo o cluster de usuário com o plano de controle e todos os pools de nós no cluster ao mesmo tempo.
  • Faça upgrade do plano de controle do cluster de usuário e deixe os pools de nós na versão atual.
  • Faça upgrade do plano de controle do cluster de usuário e faça upgrade seletivo dos pools de nós.

A abordagem adotada depende de vários fatores, como:

  • O ambiente (produção ou não produção) em que o cluster está.
  • A duração da sua janela de manutenção.
  • A versão do cluster de usuário.

Por exemplo, talvez você queira fazer upgrade do plano de controle do cluster de usuário e de todos os pools de nós em um ambiente de desenvolvimento. Mas, em um ambiente de produção com uma janela de manutenção curta, é possível fazer upgrade apenas do plano de controle, já que isso leva menos tempo e a atualização do plano de controle não deve interromper as cargas de trabalho do usuário.

Os pools de nós do balanceador de carga (pools de nós com enableLoadBalancer: true) precisam ter a mesma versão do cluster para todas as versões.

Regras de versão para gkectl

A versão de gkectl que pode ser usada para o upgrade depende da versão do cluster de destino, ou seja, a versão do cluster para o qual você está fazendo upgrade. Normalmente, você usa a mesma versão de gkectl que a versão de destino do cluster. As seguintes regras são aplicadas durante o upgrade:

  • A versão do gkectl precisa ser igual ou mais recente do que a versão secundária de destino do cluster. Por exemplo, se você estiver fazendo upgrade de um cluster 1.29 para 1.30, use o gkectl 1.30 ou mais recente. As versões de patch não importam.

  • A versão gkectl pode ser até duas versões secundárias mais recente do que a versão atual do cluster. Por exemplo, para fazer upgrade de um cluster 1.28 para 1.29, use a versão 1.29 ou 1.30 do gkectl, mas não a versão 1.31, porque ela é três versões secundárias mais recente que a versão do cluster.

A versão binária de gkectl precisa corresponder exatamente à versão de lançamento de destino quando você converte clusters não avançados em avançados. Esse requisito de versão estrita só se aplica durante o upgrade para um cluster avançado. Para todos os outros upgrades de cluster avançados, as regras de desvio de versão padrão se aplicam.

Regras de upgrade da versão de patch

Faça upgrade para a versão de patch mais recente sempre que possível para garantir que os clusters tenham as correções de segurança mais recentes. As versões de patch não afetam as regras de atualização e distorção de versão. Para uma determinada versão secundária, é possível fazer upgrade para qualquer versão de patch superior. Por exemplo, é possível fazer upgrade de 1.35.0 para 1.35.1, bem como de 1.35.1 para 1.35.3.

A seguir