Registrar um cluster do Google Cloud na sua frota

Nesta página, mostramos como adicionar um cluster do GKE à sua frota. Google Cloud 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 Google Cloud console 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 clusters em Planejar recursos da frota.

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

  • Se você quiser que a federação de identidade da carga de trabalho da frota esteja ativada no cluster registrado (recomendado), verifique se a federação de identidade da carga de trabalho para GKE está ativada no cluster. Os clusters do Autopilot têm a federação de identidade da carga de trabalho do GKE ativada por padrão.
  • Se você estiver registrando um cluster em uma frota em um projeto diferente (também conhecido como registro de projetos cruzados), configure as permissões necessárias.
  • Se você estiver registrando um cluster usando o Terraform ou o Config Connector, verifique se configurou uma Google Cloud conta de serviço para a ferramenta e se configurou essa ferramenta para se autenticar em Google Cloud:

  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

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 para GKE ativada, que oferece uma maneira consistente para aplicativos se autenticarem nos serviços e Google Cloud APIs. 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. Noconsole, acesse a página de criação do cluster relevante. Google Cloud

  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 peloconsole 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 CLI gcloud 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 Google Cloud ID do projeto 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 para 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 Google Cloud projeto para ser proprietário do cluster se não tiver configurado um projeto padrão.

Saiba mais sobre como criar diferentes tipos de cluster 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: oID do projeto em que você está criando e registrando o cluster. Google Cloud 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 Google Cloud console).

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 para GKE ativada por padrão. Quando você registra clusters pelo Google Cloud console, 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. Noconsole, acesse a página Clusters do GKE. Google Cloud

    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 CLI gcloud 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 na frota do projeto, execute o seguinte comando: Google Cloud 

    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 na frota do projeto como leve, execute o seguinte comando: Google Cloud 

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

  • Para registrar o cluster em uma frota de 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 de 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 existente em Google Cloud uma associação leve para uma associação normal, 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 Google Cloud ID do projeto 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 documentação de referência do Config Connector.

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 Google Cloud nome do recurso do 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