Fazer upgrade de um cluster de administrador ou de usuário usando 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 cluster de usuário ou administrador do Google Distributed Cloud registrado na API GKE On-Prem. Se você criou o cluster de usuário com o Terraform, é possível usar o Terraform para fazer upgrade dele. Para requisitos de upgrade, práticas recomendadas e mais informações sobre o processo de upgrade, consulte Práticas recomendadas de upgrade e Ciclo de vida e estágios dos upgrades de cluster antes de continuar.

O que é a API GKE On-Prem?

A API GKE On-Prem é hospedada pelo Google Cloud e 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 será registrado 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 registrar o cluster 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 de 7 a 10 dias após o lançamento do Google Distributed Cloud para que a versão seja disponibilizada na API GKE On-Prem.

É possível fazer upgrade diretamente para uma que esteja na mesma versão secundária ou na próxima versão secundária. Por exemplo, é possível fazer upgrade de 1.29.100 para 1.29.200 ou de 1.28.100 para 1.29.200. Não é permitido fazer upgrade para uma versão secundária mais recente que a instalada.

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. Opcionalmente, 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 do 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 Google Distributed Cloud para a qual você quer fazer upgrade. Especifique uma versão com base na saída do comando anterior. Recomendamos que você faça o 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 é concluído em 30 minutos ou mais, dependendo do tamanho do cluster. À medida que o cluster está sendo atualizado, você pode executar o comando anterior de vez em quando para saber o status atual.

Quando o upgrade for concluído, você verá algo semelhante ao seguinte 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.29.100-gke.251      abm-admin-cluster  RUNNING

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

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.29.100-gke.251   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 do cluster.

    A saída do comando é 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 é possível 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 Google Distributed Cloud para a qual você quer fazer upgrade. Especifique uma versão com base na saída do comando anterior. Recomendamos que você faça o 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 é concluído em 30 minutos ou mais, dependendo do tamanho do cluster. À medida que o cluster está sendo atualizado, você pode 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 para contêineres.

Terraform

Para fazer upgrade de um cluster usando o Terraform, use 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 os 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 Google Distributed Cloud para que você quer fazer upgrade. Especifique uma versão da saída do comando anterior. Recomendamos que você faça o 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 mais informações sobre o recurso google_gkeonprem_bare_metal_cluster, consulte a documentação de referência.