Como fazer upgrade do GKE On-Prem

Nesta página, explicamos como fazer upgrade do GKE On-Prem.

Versões de destino

A partir da versão 1.3.2 do GKE On-Prem, é 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.3.2 para 1.3.5 ou de 1.5.2 para 1.6.1.

Se sua versão atual for anterior à 1.3.2, será necessário fazer upgrades sequenciais para alcançar a versão 1.3.2 primeiro. Por exemplo, para fazer upgrade da versão 1.3.0 para 1.3.2, primeiro você precisa fazer upgrade da versão 1.3.0 para 1.3.1 e, em seguida, de 1.3.1 para 1.3.2.

Se estiver fazendo upgrade da versão 1.3.2 ou posterior para uma versão que não faça parte da próxima versão secundária, será necessário fazer upgrade por 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.3.2 para a versão 1.6.1, não será possível fazer upgrade diretamente. Primeiro, faça upgrade da versão 1.3.2 para a versão 1.4.x, em que x representa qualquer versão de patch sob essa versão secundária. Você pode fazer upgrade para a versão 1.5.x e depois para a versão 1.6.1.

Visão geral do processo de upgrade

1. Faça o download da ferramenta gkeadm. A versão do gkeadm precisa ser igual à versão de destino do upgrade.

2. Use gkeadm para fazer upgrade da estação de trabalho do administrador.

3. Na estação de trabalho do administrador, faça upgrade do cluster de administrador.

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

Política de upgrade

Veja o que é necessário depois de fazer upgrade do cluster de administrador:

• Todos os novos clusters de usuário criados precisam ter a mesma versão do cluster de administrador.

• Se você fizer upgrade de um cluster de usuários existente, precisará fazer upgrade para a mesma versão do cluster de administrador.

• Antes de fazer upgrade do cluster de administrador novamente, você precisa fazer upgrade de todos os clusters de usuário para a mesma versão do cluster de administrador atual.

Como localizar seus arquivos de configuração e informações

Ao criar a estação de trabalho de administrador atual, você preenche 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.

Quando você criou sua estação de trabalho de administrador atual, gkeadm criou um arquivo de informações para você. 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 realizar as etapas deste guia. Se esses arquivos estiverem no diretório atual e tiverem os nomes padrão, não será necessário especificá-los quando você executar gkeadm upgrade admin-workstation. Se esses arquivos estiverem em outro diretório ou se você tiver alterado os nomes dos arquivos, especifique-os usando as sinalizações --config e --info-file.

Como fazer o upgrade da estação de trabalho de administrador

Para fazer upgrade da estação de trabalho de administrador, primeiro faça o download de uma nova versão da ferramenta gkeadm e use-a para fazer upgrade da configuração da estação de trabalho de administrador. A versão de gkeadm precisa ser compatível com a versão de destino do upgrade.

Como fazer o download de gkeadm

Para fazer o download da versão atual do gkeadm, siga as instruções de download do gkeadm na página do GKE On-prem.

Como fazer upgrade da configuração de estação de trabalho de administrador

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

em que:

• [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:

  • Seu arquivo de configuração do GKE On-Prem. O nome padrão desse arquivo é config.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 da sua conta de serviço permitida na lista. 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 de conexão, registro e agente de monitoramento.

• Crie uma nova estação de trabalho de administrador e copie todos os arquivos armazenados em backup na nova estação de trabalho de administrador.

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

Como remover a antiga estação de trabalho de administrador de known_hosts

Se a estação de trabalho do administrador tiver um endereço IP estático, remova a antiga estação de trabalho do administrador do arquivo known_hosts depois de fazer upgrade da estação de trabalho do administrador.

Para remover a estação de trabalho de administrador antiga de known_hosts:

ssh-keygen -R [ADMIN_WS_IP]

[ADMIN_WS_IP] é o endereço IP da sua estação de trabalho de administrador.

Como definir o caminho do pacote no arquivo de configuração do GKE On-Prem

Na nova estação de trabalho do administrador, abra o arquivo de configuração do GKE On-Prem. Defina o valor de bundlepath como o caminho do arquivo do pacote na nova estação de trabalho de administrador:

bundlepath: "/var/lib/gke/bundles/gke-onprem-vsphere-[VERSION]-full.tgz"

[VERSION] é a versão de destino do upgrade.

Como atualizar a imagem do SO do nó e as imagens do Docker

Na nova estação de trabalho de administrador, execute o seguinte comando:

gkectl prepare --config [CONFIG_FILE] [FLAGS]

em que:

• [CONFIG_FILE] é o arquivo de configuração do GKE On-Prem na nova estação de trabalho do 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.

O comando anterior executa as seguintes tarefas:

• Se necessário, copie uma nova imagem do SO do nó para o ambiente vSphere e marque a imagem do SO como um modelo.

• Se você tiver configurado um registro particular do Docker, envie as imagens atualizadas do Docker para o registro particular do Docker.

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

Siga as etapas desta seção na nova estação de trabalho do administrador.

Antes de fazer upgrade, verifique se você tem endereços IP suficientes disponíveis para os clusters.

DHCP

Durante um upgrade, o GKE On-Prem cria um nó temporário no cluster de administrador e um nó temporário em cada cluster de usuário associado. Verifique se o servidor DHCP pode fornecer endereços IP suficientes para esses nós temporários. Para mais informações, consulte Endereços IP necessários para clusters de administrador e usuário.

IPs estáticos

Durante um upgrade, o GKE On-Prem cria um nó temporário no cluster de administrador e um nó temporário em cada cluster de usuário associado. Para o cluster de administrador e cada um dos clusters de usuário, verifique se você reservou endereços IP suficientes. Para cada cluster, você precisa ter reservado pelo menos um endereço IP a mais do que o número de nós do cluster. Para mais informações, consulte Como configurar endereços IP estáticos.

Determine o número de nós no cluster de administrador:

kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] get nodes

[ADMIN_CLUSTER_KUBECONFIG] é o caminho do arquivo kubeconfig do cluster de administrador.

Em seguida, veja os endereços reservados para o cluster de administrador:

kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -o yaml

Na saída, no campo reservedAddresses, é possível ver o número de endereços IP reservados para os nós do cluster de administrador. Por exemplo, a saída a seguir mostra que há cinco endereços IP reservados para os nós do cluster de administrador:

...
reservedAddresses:
- gateway: 21.0.135.254
  hostname: admin-node-1
  ip: 21.0.133.41
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-2
  ip: 21.0.133.50
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-3
  ip: 21.0.133.56
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-4
  ip: 21.0.133.47
  netmask: 21
- gateway: 21.0.135.254
  hostname: admin-node-5
  ip: 21.0.133.44
  netmask: 21

O número de endereços IP reservados precisa ser pelo menos um a mais do que o número de nós no cluster de administrador. Se esse não for o caso, será possível reservar um endereço extra editando o objeto Cluster.

Abra o objeto Cluster para edição:

kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG]

Em reservedAddresses, adicione mais um bloco que tenha gateway, hostname, ip e netmask.

Siga o mesmo procedimento para cada um dos clusters de usuário.

Para determinar o número de nós em um cluster de usuário:

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] get nodes

[USER_CLUSTER_KUBECONFIG] é o caminho do arquivo kubeconfig do cluster de usuário.

Para ver os endereços reservados para um cluster de usuário:

kubectl get cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
-n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME] -o yaml

onde:

• [ADMIN_CLUSTER_KUBECONFIG] é o caminho do arquivo kubeconfig do cluster de administrador;

• [USER_CLUSTER_NAME] é o nome do cluster de usuário.

Para editar o objeto Cluster de um cluster de usuário:

kubectl edit cluster --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
-n [USER_CLUSTER_NAME] [USER_CLUSTER_NAME]

(Opcional) Como desativar novos recursos do vSphere

Uma nova versão do GKE On-prem pode incluir novos recursos ou suporte para recursos específicos do VMware vSphere. Às vezes, a atualização para uma versão do GKE On-Prem ativa esses recursos automaticamente. Saiba mais sobre os novos recursos nas notas de lançamento do GKE On-Prem. Às vezes, novos recursos aparecem no arquivo de configuração do GKE On-prem.

Se você precisar desativar um novo recurso ativado automaticamente em uma nova versão do GKE On-Prem e acionado pelo arquivo de configuração, execute as etapas a seguir antes de fazer upgrade do cluster:

1. Na estação de trabalho de administrador atualizada, crie um novo arquivo de configuração com um nome diferente do arquivo de configuração atual:

   gkectl create-config --config [CONFIG_NAME]

2. Abra o novo arquivo de configuração e anote o campo do recurso. Feche o arquivo.

3. Abra o arquivo de configuração atual e adicione o campo do novo recurso. Defina o valor do campo como false ou equivalente.

4. Salve o arquivo de configuração.

Consulte as notas de lançamento antes de fazer upgrade dos clusters. Não é possível alterar declarativamente a configuração de um cluster existente depois de atualizá-la.

Como fazer upgrade do cluster de administrador

Siga as etapas desta seção na nova estação de trabalho do administrador.

Lembre-se de que a versão de destino do upgrade precisa ser igual à versão gkeadm.

Execute este comando:

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

em que:

• [ADMIN_CLUSTER_KUBECONFIG] é o arquivo kubeconfig do cluster de administrador;

• [ADMIN_CLUSTER_CONFIG_FILE] é o arquivo de configuração do cluster de administrador do GKE On-Prem na nova estação de trabalho do 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.

Observação: esse procedimento não faz upgrade de todos os nós no cluster de administrador porque alguns dos nós no cluster de administrador são os nós principais para os clusters de usuário. Eles serão atualizados quando você iniciar o upgrade dos clusters de usuário.

Como fazer upgrade de um cluster de usuário

Siga as etapas desta seção na nova estação de trabalho do administrador.

Lembre-se de que a versão de destino do upgrade precisa ser igual à versão gkeadm.

gkectl

gkectl upgrade cluster \
--kubeconfig [ADMIN_CLUSTER_KUBECONFIG] \
--config [USER_CLUSTER_CONFIG_FILE] \
--cluster-name [CLUSTER_NAME] \
[FLAGS]

em que:

• [ADMIN_CLUSTER_KUBECONFIG] é o arquivo kubeconfig do cluster de administrador;

• [CLUSTER_NAME] é o nome do cluster de usuário que você está atualizando;

• [USER_CLUSTER_CONFIG_FILE] é o arquivo de configuração do cluster de usuário do GKE On-Prem na nova estação de trabalho do 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

É possível registrar seus clusters de usuário com o console do Google Cloud durante a instalação ou depois de criá-los. É possível visualizar e fazer login nos clusters registrados do GKE On-Prem e nos clusters do Google Kubernetes Engine no menu do GKE do Console do Google Cloud.

Quando um upgrade fica disponível para clusters de usuário do GKE On-Prem, uma notificação é exibida no console do Google Cloud. Clique na notificação para exibir uma lista de versões disponíveis e um comando gkectl que pode ser executado para fazer upgrade do cluster:

1. Acesse o menu do GKE no Console do Google Cloud.

   Acesse o menu do GKE

2. Na coluna Notificações do cluster de usuário, clique em Upgrade disponível, se disponível.

3. Copie o comando gkectl upgrade cluster.

4. Na estação de trabalho do administrador, execute o comando gkectl upgrade cluster, em que [ADMIN_CLUSTER_KUBECONFIG] é o arquivo kubeconfig do cluster de administrador, [CLUSTER_NAME] é o nome do cluster de usuário que você está atualizando e [USER_CLUSTER_CONFIG_FILE] é o GKE On-Prem na configuração do cluster do usuário da nova estação de trabalho do administrador.

Como retomar um upgrade

Se o upgrade do cluster de usuário for interrompido após o upgrade do cluster de administrador, será possível retomar o upgrade do cluster de usuário 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] \
--cluster-name [CLUSTER_NAME] \
--skip-validation-all

Como retomar um upgrade de cluster de administrador

Não interrompa um upgrade do cluster de administrador. Atualmente, os upgrades de cluster de administrador nem sempre são recuperáveis. Se um upgrade de cluster de administrador for interrompido por qualquer motivo, entre em contato com o suporte para receber ajuda.

Como criar um novo cluster de usuários após um upgrade

Depois de fazer upgrade da estação de trabalho de administrador e do cluster de administrador, todos os novos clusters de usuário criados precisam ter a mesma versão que a versão de destino do upgrade.

Problemas conhecidos

Os seguintes problemas conhecidos afetam o upgrade de clusters.

Versão 1.1.0-gke.6, 1.2.0-gke.6: campo stackdriver.proxyconfigsecretname removido

O campo stackdriver.proxyconfigsecretname foi removido na versão 1.1.0-gke.6. As verificações de simulação do GKE On-prem retornarão um erro se o campo estiver presente no arquivo de configuração.

Para contornar esse problema, antes de fazer upgrade para o 1.2.0-gke.6, exclua o campo proxyconfigsecretname do arquivo de configuração.

O Stackdriver referencia a versão antiga

Antes da versão 1.2.0-gke.6, um problema conhecido impede que o Stackdriver atualize a configuração após os upgrades do cluster. O Stackdriver ainda referencia uma versão antiga, impedindo que o Stackdriver receba os recursos mais recentes do pipeline de telemetria. Esse problema pode dificultar o Suporte do Google para solucionar problemas de clusters.

Depois de fazer upgrade dos clusters para a 1.2.0-gke.6, execute o seguinte comando nos clusters de administrador e de usuário:

kubectl --kubeconfig=[KUBECONFIG] \
-n kube-system --type=json patch stackdrivers stackdriver \
-p '[{"op":"remove","path":"/spec/version"}]'

[KUBECONFIG] é o caminho para o arquivo kubeconfig do cluster.

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).

Versão 1.2.0-gke.6: Prometheus e Grafana desativados após o upgrade

Nos clusters do usuário, o Prometheus e o Grafana são desativados automaticamente durante o upgrade. No entanto, os dados de configuração e métricas não são perdidos. Nos clusters de administrador, o Prometheus e o Grafana permanecem ativados.

Para mais instruções, consulte as notas de lançamento do GKE On-Prem.

Versão 1.1.2-gke.0: os nós de cluster de usuário excluídos não são removidos do armazenamento de dados vSAN

Para mais instruções, consulte as notas de lançamento do GKE On-Prem.

Versão 1.1.1-gke.2: o disco de dados da pasta de armazenamento de dados vSAN pode ser excluído

Se você usa um armazenamento de dados vSAN, é preciso criar uma pasta para salvar o VMDK. Um problema conhecido exige que você forneça o caminho do identificador universal exclusivo (UUID, na sigla em inglês) da pasta, em vez do caminho do arquivo, para vcenter.datadisk. Essa incompatibilidade pode causar falhas nos upgrades.

Para mais instruções, consulte as notas de lançamento do GKE On-Prem.

Como fazer upgrade da versão 1.0.2-gke.3 para a versão 1.1.0-gke.6: problema do OIDC

Os clusters da versão 1.0.11, 1.0.1-gke.5 e 1.0.2-gke.3 com o OpenID Connect (OIDC) configurado não podem ser atualizados para a versão 1.1.0-gke.6. Esse problema foi corrigido na versão 1.1.1-gke.2.

Se você tiver configurado um cluster da versão 1.0.11, 1.0.1-gke.5 ou 1.0.2-gke.3 com OIDC durante a instalação, não será possível fazer upgrade. Em vez disso, crie novos clusters.

Como fazer upgrade da versão 1.0.2-gke.3 para a versão 1.0.11

A versão 1.0.2-gke.3 introduz os campos OIDC (usercluster.oidc) a seguir. Esses campos permitem fazer login em um cluster do Console do Cloud:

• usercluster.oidc.kubectlredirecturl
• usercluster.oidc.clientsecret
• usercluster.oidc.usehttpproxy

Se você quiser usar o OIDC, o campo clientsecret será obrigatório mesmo se você não quiser fazer login em um cluster do console do Cloud. Para usar o OIDC, talvez seja necessário fornecer um valor do marcador para clientsecret:

oidc:
  clientsecret: "secret"

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, o GKE On-Prem 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 novos clusters e clusters atuais.

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

• O VMware DRS está ativado. O VMware DRS requer a edição de licença do vSphere Enterprise Plus. Para saber como ativar o DRS, consulte Como ativar o VMware DRS em um cluster.
• A conta de usuário do vSphere fornecida no campo vcenter tem a permissão Host.Inventory.EditCluster.
• Há pelo menos três hosts físicos disponíveis.

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 do GKE On-Prem.

Inatividade

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. Observação: se os nós do cluster de usuário não conseguirem alcançar o plano de controle do usuário durante o upgrade, novas cargas de trabalho não serão programadas para o cluster. As cargas de trabalho já existentes não são afetadas.
Nós do cluster de usuário	Se um upgrade exigir uma alteração nos nós do cluster de usuário, o GKE On-Prem recriará os nós de maneira contínua e reagendará os pods em execução nesses nós. É possível evitar o impacto nas suas cargas de trabalho configurando PodDisruptionBudgets e regras antiafinidade apropriados (links em inglês).

Solução de problemas

Para mais informações, consulte Solução de problemas.

Novos nós criados, mas não íntegros

Sintomas

Novos nós não se registram no plano de controle do cluster de usuário ao usar o modo de balanceamento de carga manual.

Causas possíveis

A validação da entrada no nó pode estar ativada para bloquear o processo de inicialização dos nós.

Resolução

Para desativar a validação, execute:

kubectl patch machinedeployment [MACHINE_DEPLOYMENT_NAME] -p '{"spec":{"template":{"spec":{"providerSpec":{"value":{"machineVariables":{"net_validation_ports": null}}}}}}}' --type=merge

Como diagnosticar problemas de cluster usando gkectl

Use os comandos gkectl diagnose para identificar problemas de cluster e compartilhar informações do cluster com o Google. Consulte Como diagnosticar problemas de cluster.

Como executar comandos gkectl de maneira detalhada

-v5

Como registrar erros gkectl em stderr

--alsologtostderr

Como localizar registros gkectl na estação de trabalho do administrador

Mesmo que você não transmita as sinalizações de depuração, é possível visualizar os registros gkectl no seguinte diretório da estação de trabalho do administrador:

/home/ubuntu/.config/gke-on-prem/logs

Como localizar registros da API Cluster no cluster de administrador

Se uma VM não for iniciada após o início do plano de controle do administrador, tente depurar isso inspecionando os registros dos controladores da API Cluster no cluster de administrador:

1. Encontre o nome do pod de controladores da API Cluster no namespace kube-system, em que [ADMIN_CLUSTER_KUBECONFIG] é o caminho para o arquivo kubeconfig do cluster de administrador:

   kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system get pods | grep clusterapi-controllers

2. Abra os registros do pod, em que [POD_NAME] é o nome do pod. Opcionalmente, use grep ou uma ferramenta semelhante para pesquisar erros:

   kubectl --kubeconfig [ADMIN_CLUSTER_KUBECONFIG] -n kube-system logs [POD_NAME] vsphere-controller-manager