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:
- 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 conta de serviço Google Cloud para a ferramenta e se configurou essa ferramenta para se autenticar no Google Cloud:
Se você quiser usar a Google Cloud CLI para essa tarefa, instale e 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 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
No Google Cloud console, acesse a página de criação do cluster relevante.
Para criar um cluster do Autopilot, acesse a página Criar um cluster do Autopilot.
Para criar um cluster Standard zonal ou um cluster Standard regional, acesse a página Criar um cluster do Kubernetes.
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 .
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.
Preencha as seções restantes.
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.
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.
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.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 recursogoogle_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.
No console do Google Cloud , acesse a página Clusters do GKE.
Clique em Registrar ao lado do cluster não registrado que você quer adicionar à frota.
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.
- Substitua
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
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.
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.
Ative a federação de identidade da carga de trabalho para GKE adicionando o seguinte ao campo
spec
do recursoContainerCluster
. Você precisa fazer isso para clusters novos e existentes.spec: workloadIdentityConfig: workloadPool: PROJECT_ID.svc.id.goog
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.
Ative a federação de identidade da carga de trabalho da frota adicionando o seguinte ao campo
spec
do bloco de recursosGKEHubMembership
.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
- Valide o registro do cluster e veja outros detalhes de assinatura da frota, conforme descrito em Ver o status da associação de frota.
- Configurar a autenticação em clusters registrados:
- Fazer login em um cluster no console Google Cloud