Registrazione di un cluster GKE nel tuo parco risorse

Questa pagina mostra come aggiungere un cluster GKE su Google Cloud al tuo parco risorse. A seconda del progetto e del caso d'uso, puoi utilizzare la console Google Cloud, Terraform, Config Connector o Google Cloud CLI per la registrazione. Puoi anche creare e registrare un nuovo cluster in un solo passaggio utilizzando Google Cloud CLI.

Prima di iniziare

Assicurati di aver seguito i prerequisiti generali per la registrazione di un cluster.

A seconda del caso d'uso, le registrazioni dei cluster GKE possono richiedere anche quanto segue:

Registra il tuo cluster

Come hai visto nei prerequisiti, ti consigliamo di registrare i tuoi cluster GKE con la funzionalità Workload Identity abilitata, che fornisce un modo coerente per l'autenticazione delle applicazioni da parte delle applicazioni e dei servizi Google Cloud. Puoi scoprire di più sui vantaggi dell'attivazione di Workload Identity del parco risorse in Utilizzare Workload Identity del parco risorse. Tutte le opzioni seguenti consentono di abilitare Workload Identity, se necessario.

  • Se è abilitata l'intera piattaforma Anthos (operazione che puoi eseguire abilitando l'API Anthos nel tuo progetto), puoi registrare un cluster esistente nello stesso progetto dalla pagina Cluster Anthos nella console Google Cloud. Questo è il modo più semplice e veloce per registrare un cluster GKE esistente. L'utilizzo di questo approccio ti consente di visualizzare il cluster come parte del tuo parco risorse nella console e di utilizzare le funzionalità abilitate per il parco risorse, come Anthos Config Management.

  • Puoi registrare un cluster GKE nuovo o esistente (con o senza abilitare l'intera piattaforma Anthos) utilizzando Google Cloud CLI.

  • Puoi creare e registrare un cluster GKE (con o senza abilitare l'intera piattaforma Anthos) utilizzando Terraform o Config Connector.

Per registrare un cluster GKE:

Console

Per registrare un cluster:

  1. (Facoltativo) Se vuoi che il cluster registrato utilizzi Flee Workload Identity (consigliato), assicurati che GKE Workload Identity sia abilitato sul cluster. Per i cluster con GKE Workload Identity, è abilitata automaticamente la funzionalità Workload Identity del parco risorse quando le registri dalla console Google Cloud.

  2. Nella console Google Cloud, vai alla pagina Cluster Anthos. Questa pagina mostra tutti i cluster registrati.

    Vai alla pagina Cluster Anthos

  3. Fai clic su Registra cluster esistente sopra l'elenco dei cluster.

  4. Fai clic su Registrati accanto al cluster non registrato che vuoi aggiungere al tuo parco risorse.

gcloud

Puoi utilizzare Google Cloud CLI per registrare un cluster nuovo o esistente. Tieni presente che i comandi non legacy richiedono la versione dell'interfaccia a riga di comando gcloud 423.0.0 o successiva, con il componente alpha o beta installato.

La registrazione di un cluster utilizzando Google Cloud CLI fornisce per impostazione predefinita una località di appartenenza a livello di area geografica.

Crea e registra un cluster

Per creare un nuovo cluster GKE e registrarlo in un parco risorse in un solo passaggio, esegui uno dei seguenti comandi, a seconda che tu voglia creare un cluster standard o Autopilot:

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

o

gcloud beta container clusters create-auto CLUSTER_NAME \
  --fleet-project=FLEET_HOST_PROJECT

dove:

  • CLUSTER_NAME è il nome che hai scelto per il tuo cluster. Questo diventerà anche il nome di appartenenza del cluster. Se esiste già un cluster con questo nome nel tuo parco risorse scelto, il comando restituirà un errore.
  • FLEET_HOST_PROJECT è il progetto host del parco risorse per il parco risorse a cui vuoi che il cluster partecipi.
  • PROJECT_ID è l'ID progetto Google Cloud per il progetto proprietario del nuovo cluster.

Se stai creando un cluster standard, ti consigliamo di creare il cluster con GKE Workload Identity abilitato, come nell'esempio, poiché questo consente di attivare Workload Identity per il tuo cluster registrato. Ometti il flag --workload-pool se non vuoi utilizzare questa funzionalità. Per i cluster Autopilot è abilitata l'opzione Workload Identity per impostazione predefinita.

A seconda del cluster che vuoi creare, puoi anche specificare una qualsiasi delle altre opzioni per la creazione di un cluster standard di zona, standard a livello di regione o Autopilot. Potresti anche dover specificare una zona di Compute Engine se non hai configurato una zona predefinita per Google Cloud CLI e un progetto Google Cloud per possedere il cluster, se non hai configurato un progetto predefinito.

Scopri di più sulla creazione di diversi tipi di cluster GKE nella documentazione di GKE.

Registra un cluster esistente

Per registrare un cluster GKE esistente, esegui il comando seguente:

gcloud beta container clusters update CLUSTER_NAME --fleet-project=FLEET_HOST_PROJECT

dove:

  • CLUSTER_NAME è il nome del cluster. Questo diventerà anche il nome di appartenenza del cluster. Se esiste già un cluster con questo nome nel tuo parco risorse scelto, il comando restituirà un errore.
  • FLEET_HOST_PROJECT è il progetto host del parco risorse per il parco risorse a cui vuoi che il cluster partecipi.

Questo comando abilita il parco risorse Workload Identity per il cluster se nel cluster è già abilitato GKE Workload Identity.

Registra un cluster esistente (comando precedente)

Questo comando precedente è ancora supportato, anche se nella maggior parte dei casi d'uso consigliamo di registrare i cluster esistenti usando il comando update descritto nella sezione precedente. L'utilizzo di questo comando consente di scegliere di installare l'agente Connect nel cluster, necessario per l'integrazione con alcuni servizi del parco risorse, come Cloud Deploy. Per l'autenticazione su Google Cloud, puoi scegliere che l'agente utilizzi il parco risorse Workload Identity (consigliato) o un account di servizio Google Cloud.

Registra un cluster GKE con Workload Identity del parco risorse

  1. Assicurati che nel cluster sia abilitato GKE Workload Identity, seguendo le istruzioni riportate nei nostri prerequisiti.

  2. Esegui uno dei seguenti comandi per registrare il cluster:

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-uri=GKE_URI \
 --enable-workload-identity

    o

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-cluster=GKE_CLUSTER \
 --enable-workload-identity

    Sostituisci quanto segue:

    • MEMBERSHIP_NAME: il nome dell'appartenenza che scegli per rappresentare in modo univoco il cluster che viene registrato nel parco risorse.
    • GKE_URI: l'URI del cluster GKE, ad esempio: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. Puoi ottenere l'URI eseguendo gcloud container clusters list --uri.
    • GKE_CLUSTER: il location/name del cluster GKE del progetto attuale. La località può essere una zona o una regione, ad esempio us-central1-a/my-gke-cluster.

    Se vuoi installare l'agente Connect sul cluster, aggiungi il flag --install-connect-agent facoltativo a uno dei comandi, come nell'esempio seguente. Per impostazione predefinita (senza questo flag), l'agente non è installato.

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-cluster=GKE_CLUSTER \
 --enable-workload-identity \
 --install-connect-agent

Registra un cluster GKE con un account di servizio

Per registrare un cluster con l'agente Connect, specificando un account di servizio:

  1. Assicurati di aver creato un account di servizio utilizzabile dall'agente Connect, come descritto nei nostri prerequisiti.

  2. Esegui uno dei seguenti comandi:

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-uri=GKE_URI \
 --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH \
 --install-connect-agent

    o

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-cluster=GKE_CLUSTER \
 --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH \
 --install-connect-agent

    Sostituisci quanto segue:

    • MEMBERSHIP_NAME: il nome dell'appartenenza che scegli per rappresentare in modo univoco il cluster che viene registrato nel parco risorse.
    • SERVICE_ACCOUNT_KEY_PATH: percorso file locale del file JSON della chiave privata dell'account di servizio scaricato come parte dei prerequisiti. Questa chiave dell'account di servizio è archiviata come secret denominato creds-gcp nello spazio dei nomi gke-connect.
    • GKE_URI: l'URI del cluster GKE, ad esempio: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. Puoi ottenere l'URI eseguendo gcloud container clusters list --uri.
    • GKE_CLUSTER: il location/name del cluster GKE del progetto attuale. La località può essere una zona o una regione, ad esempio us-central1-a/my-gke-cluster.

Terraform

Puoi registrare i cluster GKE con Terraform utilizzando il provider google-beta. Puoi trovare un riferimento completo per la risorsa gke_hub_membership utilizzata per configurare la registrazione nel registro Terraform.

Assicurati di aver creato un account di servizio che Terraform utilizzi come descritto nei prerequisiti prima di seguire queste istruzioni.

Registra un cluster GKE

Per registrare il cluster, utilizza i seguenti blocchi nella configurazione.

  1. Specifica il provider google-beta come fornitore obbligatorio, come indicato nello snippet seguente. La versione deve essere precedente alla 3.62.0.

    terraform {
  required_providers {
    google-beta = {
      source = "hashicorp/google-beta"
      version = "3.67.0"
    }
  }
}

    Questo provider è obbligatorio se vuoi utilizzare gke_hub_membership.

  2. Imposta i seguenti valori predefiniti per il provider:

    provider "google-beta" {
  credentials = file("SERVICE_ACCOUNT_KEY_PATH")
  project = "PROJECT_ID"
}

    Sostituisci quanto segue:

    • SERVICE_ACCOUNT_KEY_PATH: percorso file locale del file JSON della chiave privata dell'account di servizio scaricato come parte dei prerequisiti. Questa chiave dell'account di servizio è archiviata come secret denominato creds-gcp nello spazio dei nomi gke-connect. Questa chiave dell'account di servizio consente a Terraform di accedere al tuo account Google Cloud.
    • PROJECT_ID: il progetto predefinito che scegli per eseguire il provisioning delle risorse Terraform.

  3. Crea un cluster GKE (facoltativo)

    Se vuoi registrare un cluster esistente, salta questo passaggio.

    resource "google_container_cluster" "TF_CLUSTER_RESOURCE_NAME" {
  provider = google-beta
  name               = "CLUSTER_NAME"
  location           = "ZONE"
  initial_node_count = 1
}

    Sostituisci quanto segue:

    • TF_CLUSTER_RESOURCE_NAME: il nome che scegli per identificare in modo univoco la risorsa google_container_cluster Terraform creata da questo blocco.
    • CLUSTER_NAME: il nome che scegli di rappresentare in modo univoco il cluster che hai creato.
    • ZONE: la zona predefinita che scegli per eseguire il provisioning della risorsa del cluster GKE. Ad esempio: us-central1-a.

  4. Registrare un'appartenenza al cluster GKE.

    resource "google_gke_hub_membership" "TF_MEMBERSHIP_RESOURCE_NAME" {
  provider = google-beta
  project = "FLEET_PROJECT_ID"
  membership_id = "MEMBERSHIP_NAME"
  endpoint {
    gke_cluster {
     resource_link = "//container.googleapis.com/CLUSTER_RESOURCE_NAME"
    }
  }
}

    Sostituisci quanto segue:

    • TF_MEMBERSHIP_RESOURCE_NAME: il nome che scegli per identificare in modo univoco la risorsa google_gke_hub_membership di Terraform creata da questo blocco.
    • FLEET_PROJECT_ID: se non viene configurato, l'appartenenza al cluster verrà creata nel progetto predefinito specificato in precedenza (PROJECT_ID). Imposta questo campo se vuoi registrare il cluster GKE in un parco risorse in un altro progetto.
    • MEMBERSHIP_NAME: il nome di appartenenza che scegli di rappresentare in modo univoco il cluster nel parco risorse.
    • CLUSTER_RESOURCE_NAME: il nome della risorsa Google Cloud per il cluster GKE. Ad esempio: projects/my-project/zones/us-west1-a/clusters/my-cluster. Se viene eseguito il provisioning del cluster con Terraform, il valore è ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

Abilita Workload Identity in un cluster GKE registrato

L'attivazione di Workload Identity utilizza la stessa configurazione della registrazione di un cluster, con i seguenti passaggi aggiuntivi.

  1. Abilita Workload Identity di GKE aggiungendo quanto segue nel blocco di risorse google_container_cluster pertinente. Devi eseguire questa operazione sia per i cluster nuovi sia per quelli esistenti.

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

    Sostituisci quanto segue:

    • PROJECT_ID: il progetto predefinito che scegli per eseguire il provisioning delle tue risorse Terraform.

  2. Abilita Fleet Workload Identity, aggiungendo quanto segue nel blocco di risorse google_gke_hub_membership pertinente.

    authority {
  issuer = "https://container.googleapis.com/v1/CLUSTER_RESOURCE_NAME"
}

    Sostituisci quanto segue:

    • CLUSTER_RESOURCE_NAME: la risorsa Google Cloud per il cluster GKE. Ad esempio: projects/my-project/zones/us-west1-a/clusters/my-cluster. Se viene eseguito il provisioning del cluster con Terraform, il valore è ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

Config Connector

Se hai installato il componente aggiuntivo Config Connector, puoi utilizzare Config Connector per registrare i cluster GKE. Assicurati di avere una versione di Config Connector precedente alla 1.47.0 e di aver creato un account di servizio come descritto nei prerequisiti.

Puoi trovare un riferimento completo per la risorsa GKEHubMembership nella documentazione di riferimento di Config Connector.

Registra un cluster GKE

Per registrare il cluster, specifica prima dove vuoi creare le risorse, seguendo le istruzioni nella guida di Config Connector. Quindi, crea un file YAML per registrarlo e, facoltativamente, crea un cluster come segue:

Crea e registra un cluster GKE

  1. Crea un cluster GKE, come nell'esempio seguente:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome che hai scelto di rappresentare in modo univoco il cluster che hai creato con Config Connector.
    • LOCATION: la zona o la regione che hai scelto per il provisioning della risorsa del cluster GKE. Ad esempio: us-central1-a.

    Per un elenco completo delle opzioni durante la creazione di un cluster GKE con Config Connector, consulta la documentazione di Config Connector.

  2. Registrare un'appartenenza al cluster GKE.

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

    Sostituisci quanto segue:

    • MEMBERSHIP_NAME: il nome dell'appartenenza che hai scelto per rappresentare in modo univoco il cluster registrato nel parco risorse.
    • MEMBERSHIP_LOCATION: la località del servizio parco risorse di cui vuoi gestire l'appartenenza al cluster. Può essere la località del cluster (consigliato) o global. Scopri di più nella pagina Gruppo di appartenenza al parco risorse. Non puoi specificare una località diversa da quella del cluster: in questo caso la registrazione non riesce.
    • CLUSTER_NAME: il nome che hai scelto di rappresentare in modo univoco il cluster che hai creato con Config Connector.

Registra il cluster in un altro progetto

Aggiungi quanto segue al campo metadata della risorsa GKEHubMembership per registrare un cluster in un parco risorse in un altro progetto.

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

Sostituisci quanto segue:

  • FLEET_PROJECT_ID: il progetto host del parco risorse che hai scelto per registrare il cluster GKE.

Registra un cluster esistente

Utilizza la configurazione seguente se vuoi registrare qualsiasi cluster esistente, indipendentemente da come è stato creato. In questo caso, devi specificare il nome completo della risorsa del cluster in modo che Config Connector possa trovarlo. Sostituisci il campo resourceRef della risorsa GKEHubMembership con:

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

Sostituisci quanto segue:

  • CLUSTER_RESOURCE_NAME: il nome della risorsa Google Cloud per il cluster GKE. Ad esempio: projects/my-project/zones/us-west1-a/clusters/my-cluster.

Se il cluster è stato creato con Config Connector, non è necessario specificare il nome completo del cluster.

Abilita Workload Identity in un cluster GKE registrato

L'attivazione di Workload Identity utilizza la stessa configurazione della registrazione di un cluster, con i seguenti passaggi aggiuntivi.

  1. Abilita GKE Workload Identity aggiungendo quanto segue nel campo spec della risorsa ContainerCluster. Devi eseguire questa operazione sia per i cluster nuovi sia per quelli esistenti.

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

    Sostituisci quanto segue:

  2. Abilita Workload Identity del parco risorse aggiungendo quanto segue nel campo spec del blocco di risorse GKEHubMembership.

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

    Sostituisci quanto segue:

    • PROJECT_ID: il progetto predefinito che hai scelto tramite l'annotazione dello spazio dei nomi per creare la risorsa del cluster GKE.
    • LOCATION: la zona o la regione che hai scelto per il provisioning della risorsa del cluster GKE. Ad esempio: us-central1-a.
    • CLUSTER_NAME: il nome che hai scelto per rappresentare in modo univoco il cluster che hai creato.

Risolvere i problemi

Se riscontri problemi durante la configurazione, consulta la nostra guida per la risoluzione dei problemi.

Che cosa succede dopo?