Como fazer upgrade de clusters do Anthos no VMware

Nesta página, explicamos como fazer upgrade de clusters do Anthos no VMware (GKE On-Prem).

Visão geral do processo de upgrade

É possível fazer upgrade diretamente para qualquer versão que esteja na mesma versão secundária ou na próxima versão secundária. Por exemplo, é possível fazer upgrade da versão 1.12.0 para 1.12.1 ou de 1.11.1 para 1.12.0.

Se você estiver fazendo upgrade para uma versão que não faz parte da próxima versão secundária, será necessário atualizar uma versão de cada versão secundária entre a versão atual e a desejada. Por exemplo, se você estiver fazendo upgrade da versão 1.10.2 para a versão 1.12.0, não será possível fazer upgrade diretamente. Primeiro, faça o upgrade da versão 1.10.2 para a versão 1.11.x e, em seguida, faça o upgrade para a versão 1.12.0.

Este tópico discute como fazer upgrade da versão 1.11.x ou 1.12.x para a versão 1.12.y.

Veja o fluxo de trabalho geral para fazer upgrade.

  1. Faça upgrade da estação de trabalho do administrador.

  2. Na estação de trabalho do administrador, instale o pacote que você usará para fazer upgrade dos clusters.

  3. Na sua estação de trabalho do administrador, faça upgrade dos clusters de usuário.

  4. Após o upgrade de todos os clusters de usuário, faça upgrade do cluster de administrador na estação de trabalho de administrador. Essa etapa é opcional, a menos que você precise dos recursos disponíveis no upgrade.

Preparar para o upgrade

Antes de criar sua estação de trabalho de administrador, você preencheu um arquivo de configuração da estação de trabalho de administrador que foi gerado por gkeadm create config. O nome padrão deste arquivo é admin-ws-config.yaml.

Além disso, a estação de trabalho tem um arquivo de informações. O nome padrão desse arquivo é o mesmo nome da estação de trabalho do administrador atual.

Localize o arquivo de configuração da estação de trabalho de administrador e o arquivo de informações. Você precisa deles para as etapas de upgrade. Se esses arquivos estiverem no diretório atual e tiverem os nomes padrão, não será necessário especificá-los ao executar os comandos de upgrade. Se esses arquivos estiverem em outro diretório ou se você tiver alterado os nomes dos arquivos, especifique-os utilizando as sinalizações --config e --info-file.

Se o arquivo de informações de saída estiver ausente, você poderá recriá-lo. Recriar um arquivo de informações se estiver ausente.

Você também deve planejar sua estratégia para qualquer período de inatividade que o upgrade causará. Consulte Sobre inatividade durante upgrades.

Faça upgrade da estação de trabalho do administrador

  1. Execute este comando para fazer o download da versão especificada do gkeadm:

    gkeadm upgrade gkeadm --target-version TARGET_VERSION
    

    Substitua TARGET_VERSION pela versão que você quer transferir por download.

  2. Execute este comando para concluir o upgrade:

    gkeadm upgrade admin-workstation --config AW_CONFIG_FILE --info-file INFO_FILE
    

    Substitua:

    • AW_CONFIG_FILE é o caminho do arquivo de configuração da estação de trabalho do administrador. É possível omitir essa sinalização se o arquivo estiver no diretório atual e tiver o nome admin-ws-config.yaml;

    • INFO_FILE é o caminho do seu arquivo de informações. Será possível omitir essa sinalização se o arquivo estiver no seu diretório atual. O nome padrão desse arquivo é o mesmo nome da estação de trabalho do administrador.

O comando anterior executa as seguintes tarefas:

  • Faça backup de todos os arquivos no diretório inicial da sua estação de trabalho de administrador atual. São eles:

    • O arquivo de configuração do cluster de administrador. O nome padrão é admin-cluster.yaml.
    • Seu arquivo de configuração do cluster de usuário. O nome padrão é user-cluster.yaml.
    • Os arquivos kubeconfig do cluster de administrador e dos clusters de usuário.
    • O certificado raiz do seu servidor vCenter. Esse arquivo precisa ter permissão de leitura e gravação de proprietário.
    • O arquivo de chave JSON para sua conta de serviço de acesso a componentes. Esse arquivo precisa ter permissão de leitura e gravação de proprietário.
    • Os arquivos de chave JSON para suas contas de serviço connect-register e logging-monitoring.
  • Cria uma nova estação de trabalho de administrador e copia todos os arquivos armazenados em backup para a nova estação de trabalho de administrador.

  • Exclui a estação de trabalho de administrador antiga.

Verificar se há endereços IP suficientes disponíveis

Antes de fazer upgrade dos clusters, verifique se você alocou endereços IP suficientes. É possível reservar outros IPs conforme necessário, conforme descrito para cada um dos IPs DHCP e estáticos. Se você tiver mais de um pool de nós, também precisará ter um endereço IP extra para cada pool para facilitar o processo de upgrade.

Consulte Gerenciar endereços IP do nó para calcular quantos endereços IP são necessários.

Verifique o pacote para fazer upgrade

Se você tiver feito upgrade da sua estação de trabalho de administrador, a versão de pacote correspondente para fazer upgrade dos clusters estará na estação de trabalho.

Se você quiser usar uma versão diferente da versão da estação de trabalho de administrador, instale o pacote correspondente manualmente. Consulte Instalar o pacote para upgrade.

Fazer upgrade de um cluster de usuários

Linha de comando

Observe o seguinte antes de continuar com o upgrade:

  • O comando gkectl upgrade executa verificações de simulação. Se elas falharem, o comando será bloqueado. Corrija as falhas ou use a sinalização --skip-preflight-check-blocking com o comando para desbloqueá-la. Só ignore as verificações de simulação se tiver certeza de que não há falhas.

  • A partir da versão 1.10, os clusters do Anthos no VMware incluem o konnectivityServerNodePort para o balanceador de carga manual. Especifique um valor apropriado para essa porta de nó e configure o balanceador de carga usando essa porta de nó, além de adicionar essa nova porta no arquivo de configuração antes de fazer upgrade. Consulte balanceamento de carga manual.

Siga estas etapas na estação de trabalho de administrador:

  1. Verifique se o campo bundlepath no arquivo de configuração do cluster de administrador corresponde ao caminho do pacote que você quer fazer upgrade.

  2. Verifique se o campo gkeOnPremVersion no arquivo de configuração do cluster de usuário corresponde à versão para a qual você quer fazer upgrade.

    Se você fizer outras alterações nos campos do arquivo de configuração do cluster de administrador ou do arquivo de configuração do cluster de usuário, essas alterações serão ignoradas durante o upgrade. Para que essas alterações entrem em vigor, primeiro faça upgrade do cluster e, em seguida, execute um comando de atualização com as alterações no arquivo de configuração para fazer outras alterações no cluster.

  3. Instale o pacote do diretório especificado no cluster.

    gkectl prepare \
     --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
     --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    

    Substitua:

    • ADMIN_CLUSTER_KUBECONFIG: o arquivo kubeconfig do cluster de administrador.
  4. Faça upgrade com o comando a seguir.

    gkectl upgrade cluster \
     --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     --config USER_CLUSTER_CONFIG_FILE \
     FLAGS
    

    Substitua:

    • USER_CLUSTER_CONFIG_FILE são os clusters do Anthos no arquivo de configuração do cluster de usuário da VMware na nova estação de trabalho de administrador.

    • FLAGS: um conjunto opcional de sinalizações. Por exemplo, inclua a sinalização --skip-validation-infra para pular a verificação da infraestrutura do vSphere.

Console

  1. Na estação de trabalho do administrador, execute o seguinte comando:

    gkectl prepare \
        --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
        --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
        --upgrade-platform
    

    Substitua:

    • ADMIN_CLUSTER_KUBECONFIG é o caminho para o arquivo kubeconfig do cluster de administrador.

    Esse comando atualiza as políticas do controle de acesso baseado em papéis (RBAC, na sigla em inglês) do controlador de usuários e que permite que o Console do Google Cloud gerencie o cluster de usuários.

  2. No console do Google Cloud, acesse a página Clusters do Anthos.

    Acesse a página de clusters do Anthos

  3. Selecione o projeto do Cloud em que o cluster de usuário está.

  4. Na lista de clusters, clique no cluster que você quer atualizar.

  5. No painel Detalhes, se o Tipo for vm Anthos (VMware), siga as etapas a seguir para excluir o cluster usando o console do Google Cloud:

    1. No painel Detalhes, clique em Mais detalhes.

    2. Na seção Princípios básicos do cluster, clique em Fazer upgrade.

    3. Na lista Clusters do Anthos na versão do VMware, selecione a versão para a qual você quer fazer upgrade.

    4. Clique em Fazer upgrade.

    Se o Tipo for externo, isso indicará que o cluster foi criado usando gkectl. Nesse caso, siga as etapas na guia Linha de comando para fazer o upgrade do cluster.

Retomar um upgrade

Se um upgrade de cluster de usuário for interrompido, será possível retomá-lo executando o mesmo comando de upgrade com a sinalização --skip-validation-all:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG_FILE \
    --skip-validation-all

Fazer upgrade do cluster de administrador

Siga as etapas desta seção na nova estação de trabalho do administrador. Verifique se gkectl e os clusters estão no nível de versão apropriado para o upgrade e se você fez o download do pacote apropriado.

  1. Verifique se o campo bundlepath no arquivo de configuração do cluster de administrador corresponde ao caminho do pacote que você quer fazer upgrade.

    Se você fizer outras alterações nos campos do arquivo de configuração do cluster de administrador, essas alterações serão ignoradas durante o upgrade. Para que essas alterações entrem em vigor, primeiro faça upgrade do cluster e, em seguida, execute um comando de atualização com as alterações no arquivo de configuração para fazer outras alterações no cluster.

  2. Execute este comando:

    gkectl upgrade admin \
        --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
        --config ADMIN_CLUSTER_CONFIG_FILE \
        FLAGS
    

    Substitua:

    • ADMIN_CLUSTER_KUBECONFIG: o arquivo kubeconfig do cluster de administrador.

    • ADMIN_CLUSTER_CONFIG_FILE são os arquivos de configuração do cluster do Anthos no cluster de administrador do VMware na nova estação de trabalho de administrador.

    • FLAGS: um conjunto opcional de sinalizações. Por exemplo, inclua a sinalização --skip-validation-infra para pular a verificação da infraestrutura do vSphere.

Se você fez o download de um pacote completo e executou os comandos gkectl prepare e gkectl upgrade admin, exclua o pacote completo para economizar espaço em disco na estação de trabalho do administrador. Use este comando:

rm /var/lib/gke/bundles/gke-onprem-vsphere-${TARGET_VERSION}-full.tgz

Como retomar um upgrade de cluster de administrador

Se o upgrade de um cluster de administrador for interrompido ou falhar, o upgrade poderá ser retomado se o ponto de verificação do cluster de administrador contiver o estado necessário para restaurar o estado antes da interrupção.

Aviso: não repare o admin-master com gkectl repair admin-master após uma tentativa de upgrade com falha. Isso fará com que o cluster de administrador fique em um estado inadequado.

Siga estas etapas:

  1. Verifique se o plano de controle do administrador está íntegro antes de iniciar a tentativa de upgrade inicial. Consulte Como diagnosticar problemas de cluster. Conforme discutido neste tópico, execute o comando gkectl diagnose cluster para o cluster de administrador.

  2. Se o plano de controle do administrador não estiver íntegro antes da tentativa inicial de upgrade, repare o plano de controle do administrador com o comando gkectl repair admin-master.

  3. Ao executar o comando de upgrade novamente depois que um upgrade for interrompido ou falhar, use o mesmo pacote e versão de destino do que você fez na tentativa anterior.

Quando você executa o comando de upgrade novamente, o upgrade retomado recria o estado do cluster de administrador do checkpoint e executa todo o upgrade novamente. A partir da versão 1.12.0, se o plano de controle do administrador não estiver íntegro, o processo de upgrade vai ser atualizado diretamente para a versão de destino sem tentar restaurar o cluster de administrador na versão de origem antes de dar continuidade ao upgrade.

O upgrade será retomado a partir do ponto em que falhou ou saiu, se o checkpoint do cluster de administrador estiver disponível. Se o checkpoint não estiver disponível, o upgrade voltará a depender do plano de controle do administrador. Portanto, o plano de controle de administrador precisa estar íntegro para prosseguir com o upgrade. Após um upgrade bem-sucedido, o checkpoint é gerado novamente.

Se o gkectl sair inesperadamente durante um upgrade de cluster de administrador, o cluster de tipo não será limpo. Antes de executar o comando de upgrade novamente para retomar o upgrade, exclua o cluster de tipo:

docker stop gkectl-control-plane && docker rm gkectl-control-plane

Depois de excluir o cluster de tipo, execute o comando de upgrade novamente.

Reverter uma estação de trabalho de administrador após um upgrade

É possível reverter a estação de trabalho do administrador para a versão usada antes do upgrade.

Durante o upgrade, gkeadm registra a versão anterior no arquivo de informações de saída. Durante a reversão, gkeadm usa a versão listada para fazer o download do arquivo mais antigo.

Para reverter a estação de trabalho do administrador para a versão anterior, faça o seguinte:

gkeadm rollback admin-workstation --config=AW_CONFIG_FILE

Será possível omitir --config=AW_CONFIG_FILE se o arquivo de configuração da estação de trabalho do administrador for o admin-ws-config.yaml padrão. Caso contrário, substitua AW_CONFIG_FILE pelo caminho do arquivo de configuração da estação de trabalho de administrador.

O comando de reversão executa as seguintes etapas:

  1. Faz o download da versão de reversão de gkeadm.
  2. Faz o backup do diretório inicial da estação de trabalho de administrador atual.
  3. Cria uma nova estação de trabalho de administrador usando a versão de reversão do gkeadm.
  4. Exclui a estação de trabalho de administrador original.

Instalar o pacote com uma versão diferente para fazer upgrade

Se você fizer upgrade da estação de trabalho, um pacote com uma versão correspondente será instalado nela para fazer o upgrade dos clusters. Se você quiser uma versão diferente, siga estas etapas para instalar um pacote para TARGET_VERSION, que é a versão para que você quer fazer upgrade.

  1. Para verificar as versões atuais de gkectl e de cluster, execute este comando. Use a sinalização --details/-d para informações mais detalhadas.

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
    

    A resposta mostra informações sobre as versões do cluster.

  2. Com base no resultado, procure os seguintes problemas e corrija-os conforme necessário.

    • Se a versão atual do cluster de administrador for mais recente que a versão secundária da TARGET_VERSION, faça upgrade de todos os clusters para uma versão secundária inferior à TARGET_VERSION.

    • Se a versão do gkectl for anterior à 1.11 e você quiser fazer upgrade para a 1.12.x, precisará fazer vários upgrades. Faça upgrade de uma versão secundária de cada vez até chegar à versão 1.11.x e siga as instruções neste tópico.

    • Se a versão gkectl for anterior à TARGET_VERSION, faça upgrade da estação de trabalho do administrador para o TARGET_VERSION.

  3. Depois de determinar que gkectl e as versões de cluster são apropriadas para um upgrade, faça o download do pacote.

    Verifique se o tarball do pacote já existe na estação de trabalho do administrador.

    stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz

    Se o pacote não estiver na estação de trabalho de administrador, faça o download dele.

    gsutil cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
    

  4. Instale o pacote.

    gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    

    Substitua ADMIN_CLUSTER_KUBECONFIG pelo caminho do arquivo kubeconfig. É possível omitir essa sinalização se o arquivo estiver no diretório atual e tiver o nome kubeconfig.

  5. Liste as versões de cluster disponíveis e verifique se a versão de destino está incluída nas versões disponíveis do cluster de usuário.

    gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details

Agora você pode criar um cluster de usuário na versão de destino ou fazer upgrade de um cluster de usuário para a versão de destino.

Como solucionar problemas do processo de upgrade

Se você tiver um problema ao seguir o processo de upgrade recomendado, siga estas recomendações para resolvê-los. Essas sugestões presumem que você começou com a configuração da versão 1.11.x e está seguindo o processo de upgrade recomendado.

Veja também Solução de problemas na criação e no upgrade de clusters.

Como solucionar problemas de upgrade de cluster de usuário

Suponha que você encontre um problema com a versão de upgrade ao fazer upgrade de um cluster de usuário. Você determina com o Suporte do Google que o problema será corrigido em uma próxima versão de patch. Você pode prosseguir da seguinte forma:

  1. Continue usando a versão atual para produção.
  2. Teste a versão do patch em um cluster que não seja de produção quando ele for lançado.
  3. Quando você tiver certeza, faça upgrade de todos os clusters de usuário de produção para a versão de lançamento do patch.
  4. Faça upgrade do cluster de administrador para a versão de lançamento do patch.

Como solucionar problemas de upgrade de cluster de administrador

Se você encontrar um problema ao fazer upgrade do cluster de administrador, entre em contato com o Suporte do Google para resolvê-lo.

Enquanto isso, com o novo fluxo de upgrade, você ainda pode aproveitar os novos recursos de cluster de usuário sem ser bloqueado pelo upgrade do cluster de administrador, o que permite reduzir a frequência de upgrade do cluster de administrador se quiser. O processo de upgrade pode prosseguir da seguinte maneira:

  1. Fazer upgrade dos clusters de usuários de produção para a versão 1.12.x
  2. Manter o cluster de administrador na versão anterior e continuar recebendo patches de segurança
  3. Testar o upgrade do cluster de administrador de 1.11.x para 1.12.x em um ambiente de teste e informar eventuais problemas
  4. Se o problema for resolvido por uma versão de patch 1.12.x, você poderá fazer upgrade do cluster de administrador de produção para essa versão de patch, se quiser

Problemas conhecidos das versões recentes

Os problemas conhecidos a seguir podem afetar os upgrades se você estiver fazendo upgrade da versão 1.7 ou posterior.

Consulte também Problemas conhecidos.

A atualização da estação de trabalho do administrador pode falhar se o disco de dados estiver quase cheio

Se você atualizar a estação de trabalho de administrador com o comando gkectl upgrade admin-workstation, o upgrade poderá falhar se o disco de dados estiver quase cheio, porque o sistema tentará fazer o backup da estação de trabalho de administrador atual localmente durante o upgrade para uma nova estação de trabalho de administrador. Se não for possível liberar espaço suficiente no disco de dados, use o comando gkectl upgrade admin-workstation com a sinalização adicional --backup-to-local=false para evitar fazer um backup local da estação de trabalho do administrador atual.

Interrupção de cargas de trabalho com PodDisruptionBudgets

Atualmente, o upgrade de clusters pode causar interrupção ou inatividade para cargas de trabalho que usam PodDisruptionBudgets (PDBs).

Falha no processo de upgrade dos nós

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}'

Apêndice

Sobre as regras do VMware DRS ativadas na versão 1.1.0-gke.6

A partir da versão 1.1.0-gke.6, os clusters do Anthos na VMware cria automaticamente regras de antiafinidade do VMware Distributed Resource Scheduler (DRS) para os nós do cluster de usuário, fazendo com que eles sejam distribuídos por pelo menos três hosts físicos no seu data center (link em inglês). A partir da versão 1.1.0-gke.6, esse recurso é ativado automaticamente para clusters novos e atuais.

Antes de fazer upgrade, verifique se o ambiente vSphere atende às condições a seguir:

Caso seu ambiente do vSphere não atenda às condições anteriores, você ainda pode fazer upgrade, mas, para atualizar um cluster de usuário de 1.3.x para 1.4.x, você precisará desativar grupos antiafinidade. Para mais informações, consulte este problema conhecido nas notas da versão sobre os clusters do Anthos no VMware.

Sobre a inatividade durante upgrades

Recurso Descrição
Cluster de administrador

Quando um cluster de administrador fica inativo, os planos de controle do cluster de usuário e as cargas de trabalho em clusters de usuário continuam em execução, a menos que tenham sido afetados por uma falha que causou a inatividade.

Plano de controle do cluster de usuário

Normalmente, não há inatividade perceptível nos planos de controle do cluster de usuário. No entanto, conexões de longa duração com o servidor da API Kubernetes podem falhar e precisam ser restabelecidas. Nesses casos, o autor da chamada da API precisa tentar novamente até estabelecer uma conexão. No pior dos casos, pode haver até um minuto de inatividade durante um upgrade.

Nós do cluster de usuário

Se um upgrade exigir uma alteração nos nós de cluster do usuário, os clusters do Anthos no VMware recriarão os nós em um ritmo contínuo e reprogramarão os pods em execução nesses nós. É possível evitar o impacto nas suas cargas de trabalho configurando PodDisruptionBudgets e regras antiafinidade apropriados.

Recriar um arquivo de informações se estiver ausente

Se o arquivo de informações de saída da estação de trabalho do administrador estiver ausente, recrie esse arquivo para continuar o upgrade. Esse arquivo foi criado durante a criação da estação de trabalho. Se você fez o upgrade, ele foi atualizado com novas informações.

O arquivo de informações de saída tem este formato:

Admin workstation version: GKEADM_VERSION
Created using gkeadm version: GKEADM_VERSION
VM name: ADMIN_WS_NAME
IP: ADMIN_WS_IP
SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY
To access your admin workstation:
ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP

Veja um exemplo de arquivo de informações de saída:

Admin workstation version: v1.10.3-gke.49
Created using gkeadm version: v1.10.3-gke.49
VM name: admin-ws-janedoe
IP: 172.16.91.21
SSH key used: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /usr/local/google/home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

Crie o arquivo em um editor, substituindo os parâmetros adequados. Salve o arquivo com um nome de arquivo igual ao da VM no diretório em que o gkeadm é executado. Por exemplo, se o nome da VM for admin-ws-janedoe, salve o arquivo como admin-ws-janedoe.