Fazer upgrade de um cluster de administrador ou usuário usando os clientes da API GKE On-Prem

Nesta página, explicamos como usar o console do Google Cloud ou a Google Cloud CLI para fazer upgrade de um administrador ou cluster de usuário do GKE em Bare Metal registrado na API GKE On-Prem. Se você criou seu cluster de usuário usando o Terraform, é possível usá-lo para fazer upgrade dele. Para requisitos de upgrade, práticas recomendadas e outras informações sobre o processo, consulte Práticas recomendadas de upgrade e Ciclo de vida e etapas dos upgrades de cluster antes de continuar.

O que é a API GKE On-Prem?

A API GKE On-Prem é uma API hospedada no Google Cloud que permite gerenciar o ciclo de vida dos clusters locais usando o Terraform e as ferramentas padrão do Google Cloud. A API GKE On-Prem é executada na infraestrutura do Google Cloud. O Terraform, o console do Google Cloud e a Google Cloud CLI são clientes da API e a usam para criar, atualizar, fazer upgrade e excluir clusters no data center. Se você criou o cluster usando um cliente padrão, ele está inscrito na API GKE On-Prem, o que significa que é possível usar os clientes padrão para gerenciar o ciclo de vida do cluster (com algumas exceções). Se você criou o cluster usando bmctl, é possível registrá-lo na API GKE On-Prem, que permite usar os clientes padrão.

Antes de começar

Configurar a CLI gcloud

Para usar a CLI gcloud ou o Terraform a fim de fazer upgrade de um cluster:

  1. Verifique se você tem a versão mais recente da CLI gcloud. Atualize os componentes da CLI gcloud, se necessário:

    gcloud components update

Requisitos do IAM

Se você não for um proprietário do projeto, 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.

Requisitos da versão

Leva cerca de 7 a 10 dias após o lançamento do GKE em Bare Metal para que a versão fique disponível na API GKE On-Prem.

É possível fazer upgrade diretamente para qualquer versão que esteja na mesma versão secundária ou na versão secundária seguinte. Por exemplo, é possível fazer upgrade da versão 1.16.1 para 1.16.2 ou de 1.15.1 para 1.16.2. Não é permitido fazer upgrade para uma versão posterior à versão secundária mais recente.

Um cluster de administrador pode gerenciar clusters de usuário que estão em uma versão secundária igual ou anterior. Os clusters de usuário gerenciados não podem ser mais que uma versão secundária anterior ao cluster de administrador. Portanto, antes de fazer upgrade de um cluster de administrador para uma nova versão secundária, verifique se todos os clusters de usuário gerenciados estão na mesma versão secundária que o cluster de administrador.

Fazer upgrade de um cluster de administrador

Console

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

    Acesse os clusters do GKE

  2. Selecione o projeto do Cloud e, em seguida, o cluster que você quer atualizar.

  3. No painel Detalhes, clique em Mais detalhes.

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

  5. Na lista Escolher versão de destino, selecione para qual versão quer fazer upgrade. Recomendamos que você faça upgrade para a versão mais recente do patch.

  6. 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 administradores será atualizado. O upgrade leva 30 minutos ou mais para ser concluído, dependendo do tamanho do cluster.

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

CLI da gcloud

  1. Se quiser, liste todos os clusters de administrador registrados no projeto para confirmar o nome e a região do cluster:

    gcloud container bare-metal admin-clusters list \
  --project=PROJECT_ID \
  --location=-

    • Substitua PROJECT_ID pelo ID do projeto host da frota em que o cluster é membro. Se você criou o cluster usando bmctl, esse é o ID do projeto no campo gkeConnect.projectID no arquivo de configuração do cluster.

    • Definir --location=- significa listar todos os clusters em todas as regiões. Se você precisar reduzir o escopo da lista, defina --location como uma região específica.

    Se você receber um erro PERMISSION_DENIED, verifique novamente o ID do projeto inserido. Se o ID do projeto estiver correto, execute gcloud auth login para fazer login na Google Cloud CLI com a conta que tem acesso ao projeto.

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

    gcloud container bare-metal admin-clusters query-version-config \
  --admin-cluster=ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

    Substitua:

    • ADMIN_CLUSTER_NAME: o nome do cluster de administrador.

    • PROJECT_ID: o ID do projeto host da frota em que o cluster é membro.

    • REGION: a região do Google Cloud em que a API GKE On-Prem executa e armazena metadados de cluster.

  3. Faça upgrade do cluster de administrador:

    gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    Substitua VERSION pela versão do GKE em Bare Metal para que você quer fazer upgrade. Especifique uma versão da saída do comando anterior. Recomendamos que você faça upgrade para a versão de patch mais recente.

    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.

    Para descobrir o status da operação, copie OPERATION_ID da saída para o comando a seguir. Abra outra janela de terminal e execute o comando.

    gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

O upgrade pode levar 30 minutos ou mais para ser concluído, dependendo do tamanho do cluster. À medida que o cluster é atualizado, é possível executar o comando anterior de vez em quando para saber o status atual.

Quando o upgrade for concluído, você verá algo semelhante a isto na janela do terminal em que executou o comando gcloud ... update:

Updated Anthos on bare metal Admin Cluster [https://gkeonprem.googleapis.com/v1/projects/example-project-1234/locations/us-central1/bareMetalAdminClusters/abm-admin-cluster].
NAME               LOCATION     VERSION     MEMBERSHIP         STATE
abm-admin-cluster  us-central1  1.16.8      abm-admin-cluster  RUNNING

Para mais informações sobre campos e sinalizações, consulte a referência do gcloud container bare-metal admin-clusters.

Fazer upgrade de um cluster de usuários

Console

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

    Acesse os clusters do GKE

  2. Selecione o projeto do Cloud e, em seguida, o cluster que você quer atualizar.

  3. No painel Detalhes, clique em Mais detalhes.

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

  5. Na lista Escolher versão de destino, selecione para qual versão quer fazer upgrade.

  6. 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. O upgrade leva 30 minutos ou mais para ser concluído, dependendo do tamanho do cluster.

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

CLI da gcloud

  1. Se quiser, liste todos os clusters de usuário registrados no projeto para confirmar o nome e a região do cluster:

    gcloud container bare-metal clusters list \
  --project=PROJECT_ID \
  --location=-

    • Substitua PROJECT_ID pelo ID do projeto host da frota em que o cluster é membro. Se você criou o cluster usando bmctl, esse é o ID do projeto no campo gkeConnect.projectID no arquivo de configuração do cluster.

    • Definir --location=- significa listar todos os clusters em todas as regiões. Se você precisar reduzir o escopo da lista, defina --location como uma região específica.

    A saída deste comando é semelhante a:

    NAME              LOCATION     VERSION  ADMIN_CLUSTER      STATE
abm-user-cluster  us-central1  1.16.8   abm-admin-cluster  RUNNING

    Se você receber um erro PERMISSION_DENIED, verifique novamente o ID do projeto inserido. Se o ID do projeto estiver correto, execute gcloud auth login para fazer login na Google Cloud CLI com a conta que tem acesso ao projeto.

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

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

    Substitua:

    • USER_CLUSTER_NAME: o nome do cluster de usuário que será atualizado.

    • PROJECT_ID: o ID do projeto host da frota em que o cluster é membro.

    • REGION: a região do Google Cloud em que a API GKE On-Prem executa e armazena metadados de cluster.

    A resposta ao comando será semelhante a esta:

    versions:
- hasDependencies: true
version: 1.15.2
- hasDependencies: true
version: 1.15.1
- hasDependencies: true
version: 1.15.0
- version: 1.14.6

    Escolha uma versão que não esteja listada em - hasDependencies: true. Neste exemplo, a única versão disponível para a qual você pode fazer upgrade do cluster de usuário é 1.14.6.

  3. Faça upgrade do cluster de usuário:

    gcloud container bare-metal clusters update USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION

    Substitua VERSION pela versão do GKE em Bare Metal para que você quer fazer upgrade. Especifique uma versão da saída do comando anterior. Recomendamos que você faça upgrade para a versão de patch mais recente.

    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.

    Para descobrir o status da operação, copie OPERATION_ID da saída para o comando a seguir. Abra outra janela de terminal e execute o comando.

    gcloud container bare-metal operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

O upgrade pode levar 30 minutos ou mais para ser concluído, dependendo do tamanho do cluster. À medida que o cluster é atualizado, é possível executar o comando anterior de vez em quando para saber o status atual.

Para mais informações sobre campos e sinalizações, consulte a referência de clusters bare-metal do gcloud.

Terraform

Para fazer upgrade de um cluster com o Terraform, utilize a mesma configuração do Terraform usada para criar o cluster.

  1. Altere para o diretório em que o arquivo de configuração do Terraform está localizado.

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

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

    Substitua:

    • USER_CLUSTER_NAME: o nome do cluster de usuário que será atualizado.

    • PROJECT_ID: o ID do projeto host da frota em que esse cluster de usuário é membro.

    • REGION: a região do Google Cloud em que a API GKE On-Prem executa e armazena metadados.

    Se você receber um erro PERMISSION_DENIED, verifique novamente o ID do projeto inserido. Se o ID do projeto estiver correto, execute gcloud auth login para fazer login na Google Cloud CLI com a conta que tem acesso ao projeto.

  3. Na configuração do Terraform, altere bare_metal_version para a versão do GKE em Bare Metal para que você quer fazer upgrade. Especifique uma versão da saída do comando anterior. Recomendamos que você faça upgrade para a versão de patch mais recente.

  4. Inicialize e crie o plano do Terraform:

    terraform init

    O Terraform instala todas as bibliotecas necessárias, como o provedor do Google Cloud.

  5. Revise a configuração e faça alterações, se necessário:

    terraform plan

  6. Aplique o plano do Terraform para criar o cluster de usuário:

    terraform apply

Para informações sobre o recurso google_gkeonprem_bare_metal_cluster, consulte a documentação de referência.