Registrar um cluster do Google Cloud na sua frota

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

Antes de começar

Verifique se você seguiu os pré-requisitos gerais para registrar um cluster.

Dependendo do seu caso de uso, o cluster do GKE nos registros do Google Cloud também pode exigir isto:

Registrar o cluster do GKE no 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. 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

Se você ativou o GKE Enterprise, é altamente recomendável registrar novos clusters em uma frota durante a criação deles. Isso ocorre porque esses clusters "nascidos na frota" são criados com as configurações padrão no nível da frota escolhidas para vários recursos empresariais e com os registros e as métricas recomendados já ativados. Saiba mais sobre isso nos seguintes guias:

Se você não ativou o GKE Enterprise, ainda poderá registrar clusters durante a criação deles seguindo estas instruções, mas não receberá configurações padrão no nível da frota.

Console

  1. No console do Google Cloud, 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 do 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 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 do 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.

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 do 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á existente, seja na frota do próprio projeto ou em uma frota em um projeto diferente (todas as opções, exceto o console do Google Cloud). Também é possível registrar alguns ou todos os clusters já existentes enquanto faz upgrade para o GKE Enterprise.

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 do 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 no Google Cloud na respectiva 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 o cluster em uma frota em um projeto diferente, use a flag --fleet-project, conforme mostrado abaixo. 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.

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 do Google Cloud proprietário do cluster 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 do 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