Registrar um cluster do Google Cloud na sua frota

Nesta página, mostramos como adicionar um cluster do GKE em Google Cloud à sua frota. Dependendo do projeto e do caso de uso, é possível usar o Google Cloud console, o Terraform, o Config Connector ou a Google Cloud CLI para registro. Também é possível criar e registrar um novo cluster em uma única etapa usando a Google Cloud CLI, o console Google Cloud ou o Terraform.

Antes de começar

Verifique se você seguiu os pré-requisitos gerais para registrar um cluster. Também recomendamos revisar as restrições gerais no registro de cluster em Planejar recursos da frota.

Dependendo do seu caso de uso, os registros de cluster do GKE no Google Cloud também podem exigir o seguinte:

Registrar o cluster do GKE em Google Cloud

Como você viu nos pré-requisitos, recomendamos registrar seus clusters do GKE com a federação de identidade da carga de trabalho da frota para GKE ativada, que oferece uma maneira consistente para aplicativos se autenticarem nos serviços e APIs do Google Cloud. Google Cloud Saiba mais sobre as vantagens de ativar a federação de identidade da carga de trabalho da frota para GKE em Usar a federação de identidade da carga de trabalho da frota para GKE. Registrar clusters usando qualquer uma das opções a seguir permite ativar a federação de identidade da carga de trabalho da frota para GKE, se necessário.

É possível escolher entre registrar um cluster novo durante a criação dele ou registrar um cluster já existente.

Registrar um novo cluster

É possível registrar clusters durante a criação deles usando as instruções a seguir.

Console

  1. No Google Cloud console, acesse a página de criação do cluster relevante.

  2. Siga as instruções na documentação do GKE para concluir as seções de criação de um cluster do Autopilot, Standard regional ou Standard zonal pelo console Google Cloud .

  3. Na seção Registro da frota, marque a caixa de seleção Registrar em uma frota. Por padrão, o nome da frota é baseado no ID do projeto.

  4. Preencha as seções restantes.

  5. Se você escolheu criar um cluster Standard e quiser que o cluster registrado use a federação de identidade da carga de trabalho da frota (recomendado), clique em Segurança no painel de navegação e verifique se Ativar federação de identidade da carga de trabalho para GKE está selecionado. Os clusters do Autopilot têm esse recurso ativado por padrão.

  6. Quando terminar de revisar os detalhes do cluster, clique em Criar para criar e registrar o cluster em uma frota.

gcloud

Esses comandos exigem a gcloud CLI versão 450.0.0 ou superior.

O registro de um cluster usando a Google Cloud CLI dá a ele um local de assinatura regional por padrão.

  • Para criar e registrar um novo cluster do GKE Autopilot, execute o seguinte comando:

    gcloud container clusters create-auto CLUSTER_NAME --enable-fleet

    Substitua CLUSTER_NAME por um nome exclusivo para o cluster que você está criando. Ele também será o nome da associação do cluster. Se já houver um cluster com esse nome na frota escolhida, o comando retornará um erro.

  • Para criar e registrar um novo cluster do GKE Autopilot como leve, execute o seguinte comando:

    gcloud container clusters create-auto CLUSTER_NAME --enable-fleet --membership-type=LIGHTWEIGHT

  • Para criar e registrar um novo cluster do GKE Standard com a federação de identidade da carga de trabalho para GKE ativada, execute o seguinte comando:

    gcloud container clusters create CLUSTER_NAME --enable-fleet \
--workload-pool=PROJECT_ID.svc.id.goog

    Substitua:

    • CLUSTER_NAME: um nome exclusivo para o cluster que você está criando. Ele também será o nome da associação do cluster. Se já houver um cluster com esse nome na frota escolhida, o comando retornará um erro.
    • PROJECT_ID: o ID do projeto Google Cloud que será proprietário do novo cluster.

    Se você estiver criando um cluster Standard, recomendamos criar o cluster com a federação de identidade da carga de trabalho para GKE ativada, porque isso ativará a federação de identidade da carga de trabalho da frota para o cluster registrado. No entanto, será possível omitir a flag --workload-pool se você não quiser usar esse recurso. Os clusters do Autopilot têm a federação de identidade da carga de trabalho do GKE ativada por padrão.

  • Para criar e registrar um novo cluster do GKE Standard como leve, execute o seguinte comando:

    gcloud container clusters create CLUSTER_NAME --enable-fleet --membership-type=LIGHTWEIGHT

Dependendo do cluster que você quer criar, também é possível especificar qualquer uma das outras opções para criar um cluster zonal padrão, regional padrão ou do Autopilot. Também será necessário especificar uma zona do Compute Engine se você não tiver configurado uma zona padrão para a Google Cloud CLI e um projeto do Google Cloud para ser proprietário do cluster se não tiver configurado um projeto padrão.

Saiba mais sobre como criar diferentes tipos de clusters do GKE na documentação do GKE.

Terraform

É possível criar e registrar clusters do GKE com o Terraform usando o provedor google. Encontre uma referência completa para o recurso google_container_cluster usado para gerenciar um cluster do GKE no registro do Terraform.

Antes de seguir estas instruções, verifique se você criou uma conta de serviço para o Terraform, conforme descrito nos pré-requisitos.

Para criar e registrar um novo cluster, adicione os seguintes blocos à sua configuração do Terraform.

  1. Especifique o provedor google como obrigatório:

    terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = "VERSION"
    }
  }
}

    Substitua VERSION pela versão 5.6.0 ou mais recente.

  2. Crie e registre um novo cluster:

    resource "google_container_cluster" "TF_CLUSTER_RESOURCE_NAME" {
  provider = google
  name               = "CLUSTER_NAME"
  location           = "ZONE"
  initial_node_count = 1
  fleet {
    project = "FLEET_HOST_PROJECT"
  }
}

    Substitua:

    • TF_CLUSTER_RESOURCE_NAME: um nome exclusivo para o novo recurso google_container_cluster que você está criando.
    • CLUSTER_NAME: um nome exclusivo para o novo cluster do GKE que você quer criar e registrar.
    • ZONE: a zona do recurso do cluster do GKE. Por exemplo, us-central1-a.
    • FLEET_HOST_PROJECT: o ID do projeto Google Cloud em que você está criando e registrando o cluster. Se ele não for definido, o cluster não será registrado em uma frota. Especifique um ID do projeto diferente se quiser registrar o cluster em uma frota em um projeto diferente.

Registrar um cluster atual

Use uma das opções a seguir para registrar clusters já existentes, seja na frota do próprio projeto ou em uma frota em um projeto diferente (todas as opções, exceto o console Google Cloud ).

Para registrar um cluster do GKE já existente:

Console

Se você quiser que o cluster use a federação de identidade da carga de trabalho da frota (recomendado), verifique se a federação de identidade da carga de trabalho para GKE está ativada no cluster antes de seguir estas instruções. Os clusters do Autopilot têm a federação de identidade da carga de trabalho do GKE ativada por padrão. Quando você registra clusters pelo console Google Cloud , a federação de identidade da carga de trabalho da frota é ativada automaticamente nos clusters com a federação de identidade da carga de trabalho para GKE.

  1. No console do Google Cloud , acesse a página Clusters do GKE.

    Acesse a página Clusters do GKE.

  2. Clique em Registrar ao lado do cluster não registrado que você quer adicionar à frota.

  3. Clique em Registrar novamente na caixa de diálogo de confirmação exibida.

gcloud

Esses comandos exigem a gcloud CLI versão 450.0.0 ou superior.

O registro de um cluster usando a Google Cloud CLI dá a ele um local de assinatura regional por padrão.

Esses dois comandos ativarão a federação de identidade da carga de trabalho da frota para o cluster se ele já estiver com a federação de identidade da carga de trabalho para GKE ativada.

  • Para registrar um cluster do GKE em Google Cloud na frota do projeto, execute o seguinte comando:

    gcloud container clusters update CLUSTER_NAME --enable-fleet

    Substitua CLUSTER_NAME pelo nome do cluster que você está registrando. Ele também será o nome da associação do cluster.

  • Para registrar um cluster do GKE em Google Cloud na frota do projeto como leve, execute o seguinte comando:

    gcloud container clusters update CLUSTER_NAME --enable-fleet --membership-type=LIGHTWEIGHT

  • Para registrar o cluster em uma frota em um projeto diferente, use a flag --fleet-project, conforme mostrado no comando a seguir. Verifique se você configurou as permissões necessárias para o registro entre projetos antes de executar esse comando.

    gcloud container clusters update CLUSTER_NAME --fleet-project=PROJECT_ID_OR_NUMBER
    • Substitua CLUSTER_NAME pelo nome do cluster que você está registrando. Ele também será o nome da associação do cluster.
    • Substitua PROJECT_ID_OR_NUMBER pelo ID do projeto ou pelo número do projeto host da frota escolhido.

  • Para registrar o cluster em uma frota em um projeto diferente como leve, use a flag --fleet-project, conforme mostrado no comando a seguir. Verifique se você configurou as permissões necessárias para o registro entre projetos antes de executar esse comando.

    gcloud container clusters update CLUSTER_NAME --fleet-project=PROJECT_ID_OR_NUMBER /
--membership-type=LIGHTWEIGHT

  • Para converter um cluster do GKE atual no Google Cloud de uma associação leve para uma regular, use o seguinte comando:

    gcloud container clusters update CLUSTER_NAME --unset-membership-type

Terraform

É possível registrar clusters do GKE com o Terraform usando o provedor google. Encontre uma referência completa para o recurso google_container_cluster usado para gerenciar um cluster do GKE no registro do Terraform.

Antes de seguir estas instruções, verifique se você criou uma conta de serviço para o Terraform, conforme descrito nos pré-requisitos.

Registrar um cluster atual

Para registrar um cluster já existente, adicione o bloco a seguir à configuração de recursos google_container_cluster do cluster:

fleet {
        project = "FLEET_HOST_PROJECT"
      }

Substitua FLEET_HOST_PROJECT pelo ID do projeto Google Cloud a que o cluster pertence ou por um ID do projeto diferente se quiser registrar o cluster em uma frota em um projeto diferente.

Ativar a federação de identidade da carga de trabalho para GKE em um cluster registrado

É possível usar o Terraform para ativar a federação de identidade da carga de trabalho para GKE em um cluster.

Para ativar a federação de identidade da carga de trabalho para GKE no seu cluster novo ou já existente, adicione o seguinte bloco à configuração de recursos google_container_cluster do cluster relevante:

  workload_identity_config {
    workload_pool = "PROJECT_ID.svc.id.goog"
  }
  ```

 Replace <code><var>PROJECT_ID</var></code> with the Google Cloud project ID for your Terraform resources.

Config Connector

Se você tiver o complemento do Config Connector instalado, poderá usar o Config Connector para registrar clusters do GKE. Verifique se você tem uma versão do Config Connector acima da versão 1.47.0 e se criou uma conta de serviço conforme descrito nos pré-requisitos.

Veja uma referência completa para o recurso GKEHubMembership na Referência do conector de configuração.

Registrar um cluster do GKE

Para registrar o cluster, primeiro especifique onde você quer criar seus recursos, seguindo as instruções no guia do Config Connector. Em seguida, crie um arquivo YAML para registrar e (opcionalmente) criar um cluster, da seguinte maneira:

Criar e registrar um cluster do GKE

  1. Crie um cluster do GKE, como no exemplo simples a seguir:

    apiVersion: container.cnrm.cloud.google.com/v1beta1
kind: ContainerCluster
metadata:
  name: CLUSTER_NAME
spec:
  location: LOCATION
  initialNodeCount: 1

    Substitua:

    • CLUSTER_NAME: o nome que você escolheu para representar exclusivamente o cluster que você criou com o Config Connector.
    • LOCATION: a zona ou região que você escolheu para provisionar o recurso de cluster do GKE. Por exemplo, us-central1-a.

    Para ver uma lista completa das opções ao criar um cluster do GKE com o Config Connector, consulte a documentação do Config Connector.

  2. Registrar uma assinatura no cluster do GKE.

    apiVersion: gkehub.cnrm.cloud.google.com/v1beta1
kind: GKEHubMembership
metadata:
  name: MEMBERSHIP_NAME
spec:
  location: MEMBERSHIP_LOCATION
  endpoint:
    gkeCluster:
      resourceRef:
        name: CLUSTER_NAME

    Substitua:

    • MEMBERSHIP_NAME: o nome da assinatura que você escolhe para representar de maneira exclusiva o cluster que está sendo registrado na frota.
    • MEMBERSHIP_LOCATION: o local do serviço da frota que você quer gerenciar a assinatura do cluster. Pode ser o próprio local do cluster (recomendado) ou global. Saiba mais em Local da frota. Não é possível especificar um local diferente do local do cluster: se fizer isso, o registro falhará.
    • CLUSTER_NAME: o nome que você escolheu para representar exclusivamente o cluster que você criou com o Config Connector.

Registrar o cluster em um projeto diferente

Adicione o seguinte ao campo metadata do recurso GKEHubMembership para registrar um cluster em uma frota de outro projeto.

   metadata:
     annotations:
       cnrm.cloud.google.com/project-id: FLEET_PROJECT_ID

Substitua:

  • FLEET_PROJECT_ID: o projeto host da frota que você escolheu para registrar o cluster do GKE.

Registrar um cluster atual

Use a configuração a seguir se quiser registrar qualquer cluster existente, independentemente de como ele foi criado. Nesse caso, você precisa especificar o nome completo do recurso do cluster para que o Config Connector possa encontrá-lo. Substitua o campo resourceRef do recurso GKEHubMembership por:

   resourceRef:
     external: //container.googleapis.com/CLUSTER_RESOURCE_NAME

Substitua:

  • CLUSTER_RESOURCE_NAME: o nome do recurso Google Cloud para o cluster do GKE. Por exemplo: projects/my-project/zones/us-west1-a/clusters/my-cluster.

Se o cluster tiver sido criado com o Config Connector, não será necessário especificar o nome do cluster totalmente qualificado.

Ativar a federação de identidade da carga de trabalho para GKE em um cluster registrado

Ativar a federação de identidade da carga de trabalho para GKE usa a mesma configuração que o registro de um cluster, com as etapas extras a seguir.

  1. Ative a federação de identidade da carga de trabalho para GKE adicionando o seguinte ao campo spec do recurso ContainerCluster. Você precisa fazer isso para clusters novos e existentes.

    spec:
  workloadIdentityConfig:
    workloadPool: PROJECT_ID.svc.id.goog

    Substitua:

  2. Ative a federação de identidade da carga de trabalho da frota adicionando o seguinte ao campo spec do bloco de recursos GKEHubMembership.

    spec:
  authority:
    issuer: https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME
}

    Substitua:

    • PROJECT_ID: o projeto padrão que você escolheu por meio da anotação de namespace para criar o recurso de cluster do GKE.
    • LOCATION: a zona ou região que você escolheu para provisionar o recurso de cluster do GKE. Por exemplo, us-central1-a.
    • CLUSTER_NAME: o nome que você escolhe para representar exclusivamente o cluster que você criou.

Solução de problemas

Se você tiver problemas durante essa configuração, consulte nosso guia de solução de problemas.

A seguir