O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Fazer upgrade de um cluster

Ao fazer upgrade da estação de trabalho de administrador, dos clusters de usuário e dos clusters de administrador do Google Distributed Cloud (somente software) para VMware, você pode adotar versões compatíveis do Kubernetes, patches de segurança e recursos da plataforma. Neste documento, mostramos como fazer upgrade do plano de controle e dos pools de nós de um cluster de usuário. Para fazer upgrade deles separadamente, consulte Fazer upgrade de pools de nós.

Antes de começar, consulte a Visão geral do upgrade para seleção de ferramentas e ordem de upgrade, Regras de versão de upgrade para distorção de versão específica da versão e requisitos do SO, e Práticas recomendadas de upgrade para listas de verificação pré-upgrade.

Antes de começar

Tenha um backup atual dos clusters de administrador e de usuário antes de iniciar o upgrade. Para mais informações, consulte Fazer backup do cluster de usuário e de administrador.
Diagnostique o cluster antes de fazer upgrade. Execute gkectl diagnose cluster para garantir que o cluster de administrador esteja íntegro e resolva todos os problemas antes de iniciar o upgrade.
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. O desvio da versão entre os clusters de administrador e de usuário depende da versão do Google Distributed Cloud. Para garantir que você possa fazer upgrade do cluster de administrador, consulte as regras de versão da sua versão.
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 update cluster com as alterações no arquivo de configuração para fazer outras alterações no cluster.

Revise suas regras de firewall

Na versão 1.29 e em versões mais recentes, as verificações de simulação do lado do servidor são ativadas por padrão. Verificações de simulação do lado do servidor não exigem regras de firewall adicionais. Em Regras de firewall para clusters de administrador, pesquise Verificações de simulação e garantir que todas as regras de firewall necessárias sejam configurados.

Com as verificações de simulação do lado do servidor, ao fazer o upgrade de um cluster de usuário usando gkectl, as verificações de simulação executadas no cluster de administrador em vez de localmente na estação de trabalho do administrador. As verificações de simulação do lado do servidor são executadas no cluster de administrador ao usar o console do Google Cloud , a Google Cloud CLI ou o Terraform para fazer o upgrade de um cluster.

Ao fazer o upgrade de um cluster de administrador, o Google Distributed Cloud implanta um cluster do Kubernetes no Docker (tipo) para hospedar temporariamente os controladores do Kubernetes necessários para atualizar o cluster de administrador. Esse cluster transitório é chamado de cluster de inicialização. As verificações de simulação do lado do servidor são executadas no cluster de inicialização quando você faz o upgrade de um cluster de administrador.

Ativar `stackdriver`

Se você criou o cluster de usuário usando gkectl, antes de fazer upgrade, verifique se a seção stackdriver no arquivo de configuração do cluster de usuário está preenchida, o que ativa stackdriver (necessário para geração de registros e monitoramento). Se o stackdriver não estiver ativado, preencha a seção stackdriver no arquivo de configuração do cluster de usuário e atualize o cluster antes de fazer o upgrade.

Se você criou o cluster usando o Terraform, o console do Google Cloud ou a CLI gcloud, o stackdriver será ativado automaticamente.

Ativar o Dataplane V2

O Dataplane V2 precisa estar ativado em todos os clusters de usuário a partir da versão 1.31. Antes de fazer upgrade de um cluster de usuário para a versão 1.31, siga estas etapas. Se você tiver dúvidas sobre como remover temporariamente a especificação NetworkPolicy, entre em contato com o Suporte do Google.

Defina enableDataplaneV2 como true no arquivo de configuração do cluster de usuário.

Se o cluster estiver usando um NetworkPolicy, remova temporariamente a especificação dele do cluster, conforme mostrado abaixo:

Verifique se há algum NetworkPolicy não do sistema aplicado ao cluster:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get networkpolicy -A -o wide \
    --field-selector metadata.namespace!=kube-system
```
Substitua USER_CLUSTER_KUBECONFIG pelo caminho do arquivo kubeconfig do cluster de usuário.

Se houver apenas políticas kube-system padrão, o comando retornará No resources found.
Se o comando anterior listar objetos NetworkPolicy, salve cada especificação NetworkPolicy em um arquivo para que seja possível reaplicar a especificação após o upgrade do cluster:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml
```
Substitua:
- NETWORK_POLICY_NAME: o nome do NetworkPolicy que você está salvando.
- NETWORK_POLICY_NAMESPACE: o namespace do NetworkPolicy.

Exclua o NetworkPolicy usando o seguinte comando:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE

Continue com o upgrade.
Após a conclusão do upgrade, se você removeu especificações NetworkPolicy que não são do sistema, replique-as com este comando:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
```

Requisitos da API do Google e do IAM

Para fazer upgrade de um cluster para a versão 1.28 ou mais recente, é necessário ativar o kubernetesmetadata.googleapis.com e conceder o papel do IAM kubernetesmetadata.publisher à conta de serviço de monitoramento de registros. Essas mudanças são necessárias para usar o Cloud Monitoring.

Ativar kubernetesmetadata.googleapis.com:
```
gcloud services enable --project PROJECT_ID  \
    kubernetesmetadata.googleapis.com
```
Substitua PROJECT_ID pelo ID do projeto do host da frota que o cluster é membro. Esse é o projeto especificado quando o cluster foi criado. Se você criou o cluster usando gkectl, esse é o ID do projeto no campo gkeConnect.projectID no arquivo de configuração do cluster.
Se a organização tiver configurado uma lista de permissões que permita o tráfego do Google APIs e de outros endereços pelo servidor proxy, adicione kubernetesmetadata.googleapis.com à lista de permissões:
Conceda o papel kubernetesmetadata.publisher à conta de serviço de monitoramento de registros:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/kubernetesmetadata.publisher"
```
Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço de monitoramento de registros.

Recursos legados bloqueados em upgrades

Os seguintes recursos legados são bloqueados durante o upgrade do cluster para a versão 1.32:

Dataplane V1 (Calico)
Configuração do balanceador de carga F5 Big IP integrado
Cluster de administrador sem alta disponibilidade
Cluster de usuário do Kubeception
Balanceador de carga Seesaw

É necessário migrar os clusters para os recursos recomendados antes de fazer upgrade para a versão 1.32.

Requisitos do IAM para upgrade de clusters de usuários

Pule esta seção se você planeja usar gkectl para o upgrade do cluster de usuários.

Se quiser usar o console do Google Cloud , a Google Cloud CLI ou o Terraform para fazer upgrade de um cluster de usuário e não for proprietário do projeto, você precisará receber o papel do Identity and Access Management roles/gkeonprem.admin no projeto do Google Cloud em que o cluster foi criado. Para ver detalhes sobre as permissões incluídas nesse papel, consulte Papéis do GKE On-Prem na documentação do IAM.

Para usar o console para fazer upgrade do cluster, você precisa, no mínimo, do seguinte:

roles/container.viewer Com esse papel, os usuários podem ver a página de clusters do GKE e outros recursos do contêiner no console. Para ver detalhes sobre as permissões incluídas nesse papel ou conceder um papel com permissões de leitura/gravação, consulte Papéis do Kubernetes Engine na documentação do IAM.
roles/gkehub.viewer Esse papel permite que os usuários vejam clusters no console. Para ver detalhes sobre as permissões incluídas nesse papel ou conceder um papel com permissões de leitura/gravação, consulte Papéis do GKE Hub na documentação do IAM.

Limitações com clusters avançados

Observe as seguintes limitações se você tiver clusters avançados ativados:

Ao fazer upgrade de clusters da versão 1.32 para a 1.33, use gkectl. Os clientes da API GKE On-Prem (o console, a CLI gcloud e o Terraform) não são compatíveis com esse caminho de upgrade específico, mas são compatíveis com upgrades a partir da versão 1.33.
Para clusters avançados na versão 1.31 em pré-lançamento ou ao converter um cluster de administrador não avançado em um cluster de administrador avançado, é necessário executar um upgrade síncrono. Na versão 1.32 e mais recentes, é possível usar a flag --async com os comandos gkectl upgrade admin e gkectl upgrade cluster para clusters avançados.

Fazer mudanças de configuração antes ou depois de um upgrade

Se você precisar fazer mudanças de configuração nos clusters, faça a atualização do cluster antes ou depois do upgrade. A única mudança na configuração do cluster para um upgrade é a versão. Dependendo da versão e do tipo do cluster, outras mudanças de configuração são ignoradas silenciosamente ou fazem com que o upgrade falhe. Para mais informações, consulte Remover mudanças incompatíveis para desbloquear o upgrade.

Verificar as versões disponíveis para upgrades do cluster

Execute o seguinte comando para ver quais versões estão disponíveis para upgrade:

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Substitua ADMIN_CLUSTER_KUBECONFIG pelo caminho para o arquivo kubeconfig do cluster de administrador.

A saída mostra a versão atual e as versões disponíveis para upgrade.

Se você planeja usar o console, a CLI gcloud ou o Terraform para o upgrade, são necessários de 7 a 14 dias após o lançamento para que a versão esteja disponível na API GKE On-Prem em todas as regiões do Google Cloud . O console lista apenas as versões disponíveis para o upgrade do cluster de usuários. As etapas para fazer upgrade de um cluster de usuário usando a CLI gcloud ou o Terraform incluem uma etapa para executar gcloud container vmware clusters query-version-config e conferir as versões disponíveis para o upgrade.

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

A forma de fazer upgrade da estação de trabalho do administrador depende de como ela foi criada: gkeadm ou gerenciado pelo usuário.

gkeadm

Localizar os arquivos necessários

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.

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. Consulte Recriar um arquivo de informações se estiver ausente.

Fazer upgrade

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

Verifique o campo adminWorkstation.diskGB no arquivo de configuração da estação de trabalho do administrador e confira se o tamanho especificado é de pelo menos 100, por exemplo:
```
adminWorkstation:
  diskGB: 100
```
Ao fazer upgrade para a versão 1.28 e mais recentes, são necessários 100 GB, e o upgrade do cluster falhará se a estação de trabalho do administrador não tiver espaço em disco suficiente.
No jump server, faça o download de gkeadm:
```
gkeadm upgrade gkeadm --target-version TARGET_VERSION
```
Substitua TARGET_VERSION pela versão para a qual você está fazendo upgrade. Especifique um número de versão completo no formato X.Y.Z-gke.N. Para conferir uma lista das versões do Google Distributed Cloud, consulte Controle de versões.

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

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

Gerenciado pelo usuário

Na estação de trabalho do administrador, navegue até um diretório em que você quer instalar uma nova versão de gkectl.

Faça o download de gkectl:
```
 gcloud storage cp gs://gke-on-prem-release/gkectl/TARGET_VERSION/gkectl ./
 chmod +x gkectl
 
```
Substitua TARGET_VERSION pela versão para a qual você está fazendo upgrade. Especifique um número de versão completo no formato X.Y.Z-gke.N. Para conferir uma lista das versões do Google Distributed Cloud, consulte Controle de versões.
Faça o download do pacote do Google Distributed Cloud. Verifique se a versão corresponde à que você usou para fazer o download de gkectl:
```
 gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz ./
 
```

Fazer upgrade do cluster de administrador

As etapas para fazer upgrade do cluster de administrador variam um pouco dependendo da versão secundária para a qual você está fazendo upgrade (a versão de destino):

1.31 e versões mais recentes

Se a versão de destino for 1.31 ou mais recente, antes de fazer upgrade dos clusters de usuário para a próxima versão secundária, faça upgrade do cluster de administrador. Na versão 1.31 e mais recentes, a versão do cluster de administrador, incluindo a versão do patch, precisa ser maior ou igual à versão do cluster de usuário. Por exemplo, se um cluster de administrador estiver na versão 1.31.1, a versão mais recente para a qual o cluster de usuário poderá ser atualizado será a 1.31.1.

Execute o seguinte comando na estação de trabalho do administrador para importar imagens do SO para o vSphere:

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

Substitua ADMIN_CLUSTER_KUBECONFIG pelo caminho para o arquivo kubeconfig do cluster de administrador.

1.30 e versões anteriores

Se a versão de destino for 1.30 ou anterior, faça upgrade de todos os clusters de usuário antes de fazer upgrade do cluster de administrador. A versão secundária do cluster de administrador precisa ser menor ou igual à versão secundária do cluster de usuário. A versão do patch não importa. Por exemplo, se um cluster de usuário estiver na versão 1.30.1, o cluster de administrador poderá ser atualizado para uma versão de patch mais recente, como 1.30.3.

Faça upgrade

gkectl

Siga as etapas desta seção na estação de trabalho do administrador. Há duas variações do comando gkectl upgrade admin:

Assíncrona:
com a variação assíncrona, o comando inicia e conclui o upgrade. Você não precisa verificar a saída do comando durante todo o upgrade. Em vez disso, é possível verificar periodicamente o progresso do upgrade executando gkectl list admin e gkectl describe admin. Para usar a variação assíncrona, inclua a flag --async no comando.

Requisitos para upgrade assíncrono:
- Compatível apenas com clusters de administrador de HA com a versão 1.29 ou mais recente.
- Todos os clusters de usuário precisam ter o Controlplane V2 ativado.
- Versão 1.31: não compatível com clusters avançados.
- Versão 1.32 e mais recentes: disponível em clusters avançados.
Síncrona:
Com a variação síncrona, o comando gkectl upgrade admin gera resposta ao comando para a estação de trabalho do administrador à medida que o upgrade avança.

Upgrade assíncrono

Na estação de trabalho do administrador, diagnostique o cluster antes de fazer upgrade:
```
gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se o comando informar erros ou avisos, consulte Diagnosticar problemas de cluster e resolva-os antes de continuar.
Inicie um upgrade assíncrono:
```
gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE \
   --async
```
Substitua:
- ADMIN_CLUSTER_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.
- ADMIN_CLUSTER_CONFIG_FILE: o caminho até o arquivo de configuração do cluster de administrador.
O comando anterior é concluído. É possível continuar usando a estação de trabalho do administrador enquanto o upgrade está em andamento.
Para ver o status do upgrade, faça o seguinte:
```
gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
A saída mostra um valor para o cluster STATE. Se o cluster ainda estiver sendo atualizado, o valor de STATE vai ser UPGRADING. Por exemplo:
```
NAME              STATE         AGE    VERSION
gke-admin-test    UPGRADING     9h     1.36.100-gke.144
```
Os valores possíveis para STATE são RUNNING, UPGRADING, RECONCILING, ERROR e UNKNOWN.

Para ver mais detalhes sobre o progresso do upgrade e os eventos do cluster, faça o seguinte:

gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG

A saída mostra o recurso personalizado OnPremAdminCluster para o cluster de administrador especificado, que inclui status e condições do cluster.

Clique para ver o exemplo de saída

Status:
 Cluster State:  RUNNING
 Conditions:
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:                 Operator NodePool is ready
   Observed Generation:     2
   Reason:                  OperatorNodePoolReady
   Status:                  True
   Type:                    ControlPlaneReady
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Cluster is running
   Observed Generation:     2
   Reason:                  ClusterRunning
   Status:                  True
   Type:                    Ready
   Last Transition Time:    2026-08-10T20:23:00Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterKubeProxyCleanedUp
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:
   Observed Generation:     2
   Reason:                  PreflightCheckPassed
   Status:                  True
   Type:                    OperatorClusterPreflightCheckSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  ProvisioningStarted
   Status:                  True
   Type:                    OperatorClusterProvisioningStarted
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  RemoteTrackerSetupComplete
   Status:                  True
   Type:                    OperatorClusterRemoteTrackerSetupSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterStalled
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  NotPresent
   Status:                  False
   Type:                    OperatorClusterWaitingOnPendingClusterID
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Operator Cluster is ready
   Observed Generation:     2
   Reason:                  OperatorClusterReady
   Status:                  True
   Type:                    OperatorClusterReady
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerSystemProfileInstalled
   Last Transition Time:    2026-08-10T15:58:20Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerAdminProfileInstalled
 Gke On Prem Version:       1.36.0-gke.527
 Last Gke On Prem Version:  1.35.300-gke.87
 Management Conditions:
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ManagementProfilesReady
   Last Transition Time:  2026-08-10T15:56:29Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerSystemManagementProfileInstalled
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerManagementProfileInstalled
 Operator Cluster Status:
   Control Plane Node Pool Status:
     Anthos Bare Metal Version:  1.36.0-gke.527
     Anthos Bare Metal Versions:
       1.36.0-gke.527:  3
     Conditions:
       Last Transition Time:  2026-08-10T20:18:20Z
       Observed Generation:   11
       Reason:                PreflightCheckPassed
       Status:                True
       Type:                  PreflightCheckSuccessful
       Last Transition Time:  2026-08-10T20:22:58Z
       Observed Generation:   11
       Reason:                NodepoolReady
       Status:                True
       Type:                  Ready
       Last Transition Time:  2026-08-10T20:22:22Z
       Observed Generation:   11
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Gke Versions:
       v1.36.0-gke.2800:        3
     Last Reconciliation Time:  2026-08-10T20:25:07Z
     Maintenance Nodes:         0
     Managed Fields:
       Label Keys:
         kubernetes.googleapis.com/cluster-name
         node.kubernetes.io/control-plane
         node.kubernetes.io/master
       Node Label Keys:
         vsphere://abcdef-1:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-2:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-3:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
       Taints:
         Effect:         PreferNoSchedule
         Key:            node-role.kubernetes.io/control-plane
     Ready Nodes:        3
     Ready Timestamp:    2026-08-10T15:54:01Z
     Reconciling Nodes:  0
     Stalled Nodes:      0
     Unknown Nodes:      0
   Data Plane Load Balancer Status:
     Conditions:
       Last Transition Time:  2026-08-10T15:39:16Z
       Observed Generation:   1
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Node Pool Location:      control-plane-nodepool
   External Manifests Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Conditions:
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                AnthosBareMetalVersion
     Status:                True
     Type:                  1.36.0-gke.527
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Dependent System Service Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Hub Registration Status:
     Membership:
       Description:  description
       Name:         name
   Gke Versions:
     v1.36.0-gke.2800:  3
   Kernel Version Conditions:
     Last Transition Time:  2026-08-10T15:39:23Z
     Reason:                kernelVersionCheckPassed
     Status:                True
     Type:                  kernelVersionCheckSuccessful
   System Service Conditions:
     Last Transition Time:  2026-08-10T20:12:26Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling

Quando o upgrade for concluído, gkectl list admin vai mostrar um STATE de RUNNING:
```
NAME              STATE         AGE    VERSION
gke-admin-test    RUNNING       9h     1.36.100-gke.144
```
Além disso, quando o upgrade for concluído, gkectl describe admin vai mostrar um campo Last GKE On Prem Version em Status. Por exemplo:
```
Status:
  Cluster State:  RUNNING
  Last GKE On Prem Version:  1.36.0-gke.1
```

Resolver problemas de upgrade assíncrono

Para fazer um upgrade assíncrono, o tempo limite é baseado no número de nós no cluster. Se o upgrade demorar mais que o tempo limite, o estado do cluster vai ser alterado de UPGRADING para ERROR, com um evento dizendo que a operação de upgrade expirou. O estado ERROR significa que o upgrade está demorando mais do que o esperado, mas não foi encerrado. O controlador continua a reconciliação e a repetir a operação. Quando um upgrade é bloqueado ou falha, é possível executar gkectl diagnose para verificar problemas comuns do cluster. Com base no resultado, é possível decidir se você vai realizar uma correção manual ou entrar em contato com o Suporte doGoogle Cloud para receber mais ajuda.

Upgrade síncrono

Na estação de trabalho do administrador, diagnostique o cluster antes de fazer upgrade:
```
gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se o comando informar erros ou avisos, consulte Diagnosticar problemas de cluster e resolva-os antes de continuar.
Fazer upgrade do cluster de administrador
```
gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE
```
Substitua:
- ADMIN_CLUSTER_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.
- ADMIN_CLUSTER_CONFIG_FILE: o caminho até o arquivo de configuração do cluster de administrador.
O comando gkectl upgrade executa verificações de simulação. Se as verificações de simulação falharem, o comando vai ser bloqueado. Corrija as falhas ou use a sinalização --skip-preflight-check-blocking com o comando para desbloqueá-la.
Se você estiver fazendo upgrade para a versão 1.14.0 ou superior, um novo arquivo kubeconfig será gerado para o cluster de administrador que substituirá qualquer arquivo existente. Para acessar os detalhes do cluster no arquivo, execute o seguinte comando:
```
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```

CLI da gcloud

Faça upgrade do cluster de administrador usando a CLI gcloud.

Atualize a versão da plataforma para a versão de destino:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --required-platform-version=VERSION \
    --async
```
Substitua:
- ADMIN_CLUSTER_NAME: o nome do cluster de administrador.
- REGION: a região do Google Cloud em que o cluster de administrador é gerenciado.
- VERSION: a versão de destino para a qual você está fazendo upgrade.
Esse comando retorna um ID de operação. É possível monitorar o progresso usando gcloud container vmware operations describe.
Depois de concluir a atualização da versão da plataforma, atualize a versão do cluster de administrador:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --version=VERSION \
    --async
```
Esta etapa conclui o upgrade do cluster de administrador para a versão de destino.

Fazer upgrade de um cluster de usuários

É possível usar gkectl, o console, a CLI gcloud ou o Terraform para fazer upgrade de um cluster de usuário. Para informações sobre como decidir qual ferramenta usar, consulte Escolher uma ferramenta para fazer upgrade de clusters.

Console

O upgrade de um cluster de usuário exige algumas alterações no cluster de administrador. O console faz o seguinte automaticamente:

Registra o cluster de administrador na API GKE On-Prem, se ele ainda não estiver registrado.
Faz o download e implanta um pacote de componentes no cluster de administrador. A versão dos componentes corresponde à versão especificada para o upgrade. Esses componentes permitem que o cluster de administrador gerencie clusters de usuário nessa versão.

Para fazer upgrade de um cluster de usuário, faça o seguinte:

No console, acesse a página Visão geral dos clusters do Google Kubernetes Engine.

Acesse os clusters do GKE
Selecione o projeto do Google Cloud e, em seguida, o cluster que você quer atualizar.
No painel Detalhes, clique em Mais detalhes.
Na seção Princípios básicos do cluster, clique em Fazer upgrade.
Na lista Escolher versão de destino, selecione para qual versão quer fazer upgrade. A lista selecionada contém apenas as versões de patch mais recentes.
Clique em Fazer upgrade.

Antes do upgrade do cluster, as verificações de simulação são executadas para validar o status do cluster e a integridade do nó. Se as verificações de simulação forem aprovadas, o cluster de usuário será atualizado. A atualização leva cerca de 30 minutos.

Para ver o status do upgrade, clique em Mostrar detalhes na guia Detalhes do cluster.

CLI da gcloud

O upgrade de um cluster de usuário exige algumas alterações no cluster de administrador. O comando gcloud container vmware clusters upgrade faz o seguinte automaticamente:

Registra o cluster de administrador na API GKE On-Prem, se ele ainda não estiver registrado.
Faz o download e implanta um pacote de componentes no cluster de administrador. A versão dos componentes corresponde à versão especificada para o upgrade. Esses componentes permitem que o cluster de administrador gerencie clusters de usuário nessa versão.

Para fazer upgrade de um cluster de usuário, faça o seguinte:

Atualize os componentes da CLI do Google Cloud:
```
gcloud components update
```

Veja uma lista das versões disponíveis para upgrade:

gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

A saída deste comando é semelhante a:

versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

Você pode ignorar a mensagem após a lista de versões. Não importa se a versão em que você está fazendo upgrade está instalada no cluster de administrador. O comando upgrade faz o download e implanta um pacote de componentes que corresponde à versão especificada no comando upgrade.

Faça upgrade do cluster.
```
gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION
```
Substitua VERSION pelo atributo "Google Distributed Cloud" para a qual você quer fazer upgrade. Especifique uma versão na saída do comando anterior. Recomendamos que você faça upgrade para a versão mais recente do patch.

A saída deste comando terá esta aparência:
```
Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.
```
No exemplo de saída, a string operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 é o OPERATION_ID da operação de longa duração. Descubra o status da operação executando o comando a seguir em outra janela do terminal:
```
gcloud container vmware operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION
```

gkectl

Preparar-se para fazer upgrade de um cluster de usuário

Execute as etapas a seguir na estação de trabalho do administrador:

Verifique se o cluster de usuário está íntegro antes de iniciar a tentativa de upgrade inicial. Consulte Diagnosticar problemas de cluster. Execute gkectl diagnose cluster no cluster de usuário e resolva os problemas.
Siga esta etapa apenas se o TARGET_VERSION for 1.30 ou anterior ou se você estiver fazendo upgrade do cluster de usuário para uma versão diferente do cluster de administrador. Execute gkectl prepare para importar imagens do SO para o vSphere:
```
gkectl prepare \
  --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se o cluster tiver um pool de nós do Windows, execute gkectl prepare windows e atualize o campo osImage para o pool de nós. Para instruções detalhadas, consulte Fazer upgrade do cluster de usuário com pools de nós do Windows.
No arquivo de configuração do cluster de usuário, defina gkeOnPremVersion como a versão de destino do upgrade.

Executar verificações de simulação

Ao fazer upgrade para a versão 1.29 e mais recentes, é possível executar as verificações de simulação antes de fazer upgrade de um cluster de usuário:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG \
    --dry-run

Substitua USER_CLUSTER_CONFIG pelo caminho para o arquivo de configuração do cluster de usuário.

Com a flag --dry-run, o gkectl upgrade cluster executa as verificações de simulação, mas não inicia o processo de upgrade. Embora versões anteriores do Google Distributed Cloud Run executem verificações de simulação, elas não podem ser executadas separadamente do upgrade. Ao adicionar a flag --dry-run, é possível encontrar e corrigir problemas que as verificações de simulação encontram no cluster de usuário antes do upgrade.

Executar `gkectl upgrade cluster`

Há duas variações do comando gkectl upgrade cluster:

Assíncrona: (recomendada)
com a variação assíncrona, o comando inicia e conclui o upgrade. Você não precisa verificar a saída do comando durante todo o upgrade. Em vez disso, é possível verificar periodicamente o progresso do upgrade executando gkectl list clusters e gkectl describe clusters. Para usar a variação assíncrona, inclua a flag --async no comando.
- Versão 1.31: não disponível em clusters avançados.
- Versão 1.32 e mais recentes: disponível em clusters avançados.
Síncrona:
Com a variação síncrona, o comando gkectl upgrade cluster gera resposta ao comando para a estação de trabalho do administrador à medida que o upgrade avança.

Upgrade assíncrono

Pule esta etapa se você estiver fazendo upgrade para uma versão mais recente que 1.16.

Se você estiver usando credenciais preparadas e um registro particular para o cluster de usuário, verifique se a credencial do registro particular está preparada antes de fazer upgrade do cluster de usuário. Para saber como preparar a credencial de registro particular, consulte Configurar credenciais preparadas para clusters de usuários.
Faça um diagnóstico do cluster para garantir que ele esteja íntegro:
```
gkectl diagnose cluster \
    --kubeconfig <var>ADMIN_CLUSTER_KUBECONFIG</var>
```
Se o comando informar erros ou avisos, consulte Diagnosticar problemas de cluster e resolva-os antes de continuar.
Na estação de trabalho do administrador, inicie um upgrade assíncrono:
```
gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG \
  --async
```
O comando anterior é concluído. É possível continuar usando a estação de trabalho do administrador enquanto o upgrade está em andamento.
Para ver o status do upgrade, faça o seguinte:
```
gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
A saída mostra um valor para o cluster STATE. Se o cluster ainda estiver sendo atualizado, o valor de STATE vai ser UPGRADING. Exemplo:
```
NAMESPACE             NAME    READY   STATE       AGE   VERSION
my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.36.0-gke.1
```
Os valores possíveis para STATE são UPGRADING, DELETING, UPDATING, RUNNING, RECONCILING, ERROR e UNKNOWN.

Para ver mais detalhes sobre o progresso do upgrade e os eventos do cluster, faça o seguinte:

gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --cluster USER_CLUSTER_NAME -v 5

A saída mostra o recurso personalizado OnPremUserCluster para o cluster de usuário especificado, que inclui status, condições e eventos do cluster.

Clique para ver o exemplo de saída

Status: Cluster State: RUNNING Conditions: Last Transition Time: 2026-08-10T21:29:07Z Message: Cluster is running Observed Generation: 2 Reason: ClusterRunning Status: True Type: Ready Last Transition Time: 2026-08-10T21:12:05Z Message: Operator NodePool is ready Observed Generation: 2 Reason: OperatorNodePoolReady Status: True Type: ControlPlaneReady Last Transition Time: 2026-08-10T16:25:08Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerUserProfileInstalled Last Transition Time: 2026-08-10T21:29:07Z Message: Node pools are running Observed Generation: 2 Reason: NodePoolsRunning Status: True Type: NodePoolsReady Last Transition Time: 2026-08-10T21:29:56Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterKubeProxyCleanedUp Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: PreflightCheckPassed Status: True Type: OperatorClusterPreflightCheckSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: ProvisioningStarted Status: True Type: OperatorClusterProvisioningStarted Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: RemoteTrackerSetupComplete Status: True Type: OperatorClusterRemoteTrackerSetupSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterStalled Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: NotPresent Status: False Type: OperatorClusterWaitingOnPendingClusterID Last Transition Time: 2026-08-10T18:23:16Z Message: Operator Cluster is ready Observed Generation: 2 Reason: OperatorClusterReady Status: True Type: OperatorClusterReady Gke On Prem Version: 1.36.0-gke.527 Last Gke On Prem Version: 1.35.300-gke.87 Operator Cluster Status: Control Plane Node Pool Status: Anthos Bare Metal Version: 1.36.0-gke.527 Anthos Bare Metal Versions: 1.36.0-gke.527: 3 Conditions: Last Transition Time: 2026-08-10T21:07:22Z Observed Generation: 11 Reason: PreflightCheckPassed Status: True Type: PreflightCheckSuccessful Last Transition Time: 2026-08-10T21:12:05Z Observed Generation: 11 Reason: NodepoolReady Status: True Type: Ready Last Transition Time: 2026-08-10T21:11:24Z Observed Generation: 11 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Versions: v1.36.0-gke.2800: 3 Last Reconciliation Time: 2026-08-10T21:28:02Z Maintenance Nodes: 0 Managed Fields: Label Keys: node.kubernetes.io/control-plane node.kubernetes.io/master Node Label Keys: vsphere://abcdef-1: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-2: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-3: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name Ready Nodes: 3 Ready Timestamp: 2026-08-10T16:24:02Z Reconciling Nodes: 0 Stalled Nodes: 0 Unknown Nodes: 0 Data Plane Load Balancer Status: Conditions: Last Transition Time: 2026-08-10T16:08:47Z Observed Generation: 1 Reason: ReconciliationCompleted Status: False Type: Reconciling Node Pool Location: load-balancer-nodepool External Manifests Conditions: Last Transition Time: 2026-08-10T16:12:25Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Conditions: Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: AnthosBareMetalVersion Status: True Type: 1.36.0-gke.527 Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Dependent System Service Conditions: Last Transition Time: 2026-08-10T16:25:26Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Hub Registration Status: Membership: Description: description Name: name Gke Versions: v1.36.0-gke.2800: 6 Kernel Version Conditions: Last Transition Time: 2026-08-10T16:08:53Z Reason: kernelVersionCheckPassed Status: True Type: kernelVersionCheckSuccessful System Service Conditions: Last Transition Time: 2026-08-10T21:04:39Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Events: Type Reason Age From Message

Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:

New ClusterState condition: UPGRADING Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 56m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:46:33 +0000 UTC Normal StatusChanged 54m (x2 over 56m) onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePoolClaim is currently in the progress of rolling update: Condition "NodeRecreationUpdateInProgress" ready, reason: "NodeRecreationUpdateInProgress", message: "Cannot further mark old InventoryMachines for recreation due to MinReadyNodesRequired requirement. Current process: There are still old InventoryMachines: [my-uc-cp-99cc4wxzvx8ww829-2 my-uc-cp-99cc4wxzvx8ww829-1]; New ready count (0) does not match desired count (3)" Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" generation 7 hasn't been observed Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:48:58 +0000 UTC Normal StatusChanged 30m (x3 over 58m) onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: True, ClusterRunning, Cluster is running Normal ControlPlaneUpgradeFinished 30m (x3 over 58m) onprem-user-cluster-controller Operator NodePool is ready Normal StatusChanged 29m (x9 over 47m) onprem-user-cluster-controller (combined from similar events): OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateNodePools, Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal NodePoolsUpgradeStarted 29m onprem-user-cluster-controller Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal StatusChanged 13m onprem-user-cluster-controller OnPremUserCluster status changed:
New GKEOnPremVersion: "1.36.0-gke.527"
New ClusterState condition: RUNNING
New Ready condition: True, ClusterRunning, Cluster is running

Quando o upgrade for concluído, gkectl list clusters vai mostrar um STATE de RUNNING:
```
NAMESPACE             NAME    READY   STATE     AGE     VERSION
my-uc-gkeonprem-mgmt  my-uc   True    RUNNING   9h      1.36.0-gke.1
```
Além disso, quando o upgrade for concluído, gkectl describe clusters vai mostrar um campo Last GKE On Prem Version em Status. Por exemplo:
```
Status:
Cluster State:  RUNNING
Last GKE On Prem Version:  1.36.0-gke.1
```

Resolver problemas de upgrade assíncrono

Geralmente, uma expiração é o resultado de um impasse causado por um PodDisruptionBudget (PDB). Nesse caso, não é possível remover os pods dos nós antigos e os nós antigos não podem ser reduzidos. Se a remoção do pod demorar mais de 10 minutos, vamos gravar um evento no objeto OnPremUserCluster. É possível capturar o evento executando gkectl describe clusters. Ajuste o PDB para permitir que o nó seja reduzido. Depois disso, vai ser possível continuar e concluir o upgrade.

Evento de exemplo:

Warning  PodEvictionTooLong  96s (x2 over 4m7s)  onprem-user-cluster-controller
Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.

Além disso, quando um upgrade é bloqueado ou falha, é possível executar gkectl diagnose para verificar problemas comuns do cluster. Com base no resultado, é possível decidir se você vai realizar uma correção manual ou entrar em contato com o suporte doGoogle Cloud para receber assistência.

Upgrade síncrono

O comando gkectl upgrade executa verificações de simulação. Se as verificações de simulação falharem, o comando vai ser bloqueado. Corrija as falhas ou use a flag --skip-preflight-check-blocking. Só ignore as verificações de simulação se tiver certeza de que não há falhas críticas.

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

Pule esta etapa se você estiver fazendo upgrade para uma versão mais recente que 1.16.

Se você estiver usando credenciais preparadas e um registro particular para o cluster de usuário, verifique se a credencial do registro particular está preparada antes de fazer upgrade do cluster de usuário. Para saber como preparar a credencial de registro particular, consulte Configurar credenciais preparadas para clusters de usuários.
Faça um diagnóstico do cluster para garantir que ele esteja íntegro:
```
gkectl diagnose cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG
```
Se o comando informar erros ou avisos, consulte Diagnosticar problemas de cluster e resolva-os antes de continuar.

Fazer upgrade do cluster:

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG

Se você estiver fazendo upgrade para a versão 1.14.0 ou mais recente, um novo arquivo kubeconfig será gerado para o cluster de usuário que substituirá qualquer arquivo existente. Para acessar os detalhes do cluster no arquivo, execute o seguinte comando:
```
kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG
```

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 flag --skip-validation-all:

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

Terraform

Atualize os componentes da CLI do Google Cloud:
```
gcloud components update
```
Registre o cluster de administrador na API GKE On-Prem, caso ainda não tenha feito isso. Depois que o cluster tiver sido registrado na API GKE On-Prem, não será necessário fazer essa etapa novamente.

Veja uma lista das versões disponíveis para upgrade:

gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

Substitua:

USER_CLUSTER_NAME: o nome do cluster do usuário.
PROJECT_ID: o ID do projeto da frota em que o cluster de usuário é membro. Esse é o projeto especificado quando o cluster foi criado. Se você criou o cluster usando gkectl, esse é o ID do projeto no campo gkeConnect.projectID no arquivo de configuração do cluster.
REGION: a região do Google Cloud em que a API GKE On-Prem é executada e armazena os metadados. No arquivo main.tf usado para criar o cluster de usuário, a região fica no campo location do recurso do cluster.

A saída deste comando é semelhante a:

versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

Faça o download da nova versão dos componentes e implante-os no cluster de administrador:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --required-platform-version=VERSION
```
Esse comando faz o download da versão dos componentes especificados em --required-platform-version no cluster de administrador e, em seguida, implanta os componentes. Esses componentes permitem que o cluster de administrador gerencie clusters de usuário nessa versão.
No arquivo main.tf usado para criar o cluster de usuário, mude on_prem_version no recurso do cluster para a nova versão.
Inicialize e crie o plano do Terraform:
```
terraform init
```
O Terraform instala todas as bibliotecas necessárias, como o provedor do Google Cloud.
Revise a configuração e faça alterações, se necessário:
```
terraform plan
```
Aplique o plano do Terraform para criar o cluster de usuário:
```
terraform apply
```

Remover o pacote completo

Se você fez o download de um pacote completo e executou gkectl prepare e fez upgrade do cluster de administrador e de todos os clusters de usuário, exclua o pacote completo para economizar espaço em disco na estação de trabalho do administrador. Execute o comando a seguir para excluir o pacote completo:

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 plano de controle do administrador com gkectl repair admin-master após uma tentativa de upgrade com falha. Isso faz com que o cluster de administrador entre em um estado inadequado.

Siga estas etapas:

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

Faz o download da versão de reversão de gkeadm.
Faz o backup do diretório inicial da estação de trabalho de administrador atual.
Cria uma nova estação de trabalho de administrador usando a versão de reversão do gkeadm.
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.

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.
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.
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.
```
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
```
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 flag se o arquivo estiver no diretório atual e tiver o nome kubeconfig.

Observação:: por padrão, é feito o download do pacote normal em vez do pacote completo. O pacote completo contém todas as imagens de contêiner e de VM, enquanto o pacote normal faz o download das imagens do contêiner e da VM do Google Cloud Platform para a estação de trabalho do administrador durante a instalação. Para usar o pacote completo, defina o caminho do pacote no comando de instalação como gke-onprem-vsphere-TARGET_VERSION-full.tgz.
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:

Continue usando a versão atual para produção.
Teste a versão do patch em um cluster que não seja de produção quando ele for lançado.
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.
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:

Fazer upgrade dos clusters de usuários de produção para a versão 1.12.x
Manter o cluster de administrador na versão anterior e continuar recebendo patches de segurança
Testar o upgrade do cluster de administrador de 1.11.x para 1.12.x em um ambiente de teste e informar eventuais problemas
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 flag 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

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, os nós poderão 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.

Liste todos os objetos PodDisruptionBudget no cluster de usuário que não permitem interrupções:

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

Substitua USER_CLUSTER_KUBECONFIG pelo caminho do arquivo kubeconfig do cluster de usuário.

Os PDBs padrão kube-system/log-aggregator e kube-system/prometheus aparecem na saída com disruptionsAllowed: 0 quando não têm pods correspondentes e status.expectedPods é 0. Como esses PDBs não bloqueiam a drenagem de nós, eles podem ser ignorados.

Mais informações sobre o upgrade

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 Google Distributed Cloud 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 data center. 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:

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.
O nome de usuário do vSphere fornecido no arquivo de confirmação de credenciais 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 Google Distributed Cloud.

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 Google Distributed Cloud 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.

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: /home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /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.

A seguir

Documentação de referência da gcloud CLI
Documentação de referência do Terraform
- google_gkeonprem_vmware_cluster
- google_gkeonprem_vmware_node_pool

Fazer upgrade de um cluster Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Revise suas regras de firewall

Ativar stackdriver

Ativar o Dataplane V2

Requisitos da API do Google e do IAM

Recursos legados bloqueados em upgrades

Requisitos do IAM para upgrade de clusters de usuários

Limitações com clusters avançados

Fazer mudanças de configuração antes ou depois de um upgrade

Verificar as versões disponíveis para upgrades do cluster

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

gkeadm

Localizar os arquivos necessários

Fazer upgrade

Gerenciado pelo usuário

Fazer upgrade do cluster de administrador

1.31 e versões mais recentes

1.30 e versões anteriores

Faça upgrade

gkectl

Upgrade assíncrono

Resolver problemas de upgrade assíncrono

Upgrade síncrono

CLI da gcloud

Fazer upgrade de um cluster de usuários

Console

CLI da gcloud

gkectl

Preparar-se para fazer upgrade de um cluster de usuário

Executar verificações de simulação

Executar gkectl upgrade cluster

Upgrade assíncrono

Resolver problemas de upgrade assíncrono

Upgrade síncrono

Retomar um upgrade

Terraform

Remover o pacote completo

Como retomar um upgrade de cluster de administrador

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

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

Como solucionar problemas do processo de upgrade

Como solucionar problemas de upgrade de cluster de usuário

Como solucionar problemas de upgrade de cluster de administrador

Problemas conhecidos das versões recentes

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

Interrupção de cargas de trabalho com PodDisruptionBudgets

Falha no processo de upgrade dos nós

Mais informações sobre o upgrade

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

Sobre a inatividade durante upgrades

Recriar um arquivo de informações se estiver ausente

A seguir

Fazer upgrade de um cluster

Ativar `stackdriver`

Executar `gkectl upgrade cluster`