Utilizzo di Connect Gateway

Questa pagina descrive come utilizzare il gateway di Connect per connetterti a un cluster registrato. Prima di leggere questa guida, dovresti acquisire familiarità con i concetti della nostra panoramica. La guida presuppone che l'amministratore del progetto abbia già configurato il gateway e che ti abbia fornito i ruoli e le autorizzazioni necessari.

Prima di iniziare

  • Assicurati di aver installato i seguenti strumenti a riga di comando:

    • La versione più recente di Google Cloud CLI, lo strumento a riga di comando per interagire con Google Cloud.
    • kubectl

    Se utilizzi Cloud Shell come ambiente shell per interagire con Google Cloud, questi strumenti sono installati automaticamente.

  • Assicurati di aver inizializzato gcloud CLI per utilizzarlo con il tuo progetto.

Accedi al tuo account Google Cloud

Puoi utilizzare il tuo account Google Cloud o un account di servizio Google Cloud per interagire con i cluster connessi tramite l'API gateway.

Segui le istruzioni in Autorizzare gli strumenti di Google Cloud CLI per accedere al tuo account utente. Il gateway di Connect supporta la impersonificazione degli account di servizio, quindi anche se hai eseguito l'accesso al tuo account utente puoi utilizzarlo per interagire con i cluster, come vedrai nelle sezioni seguenti.

Seleziona un cluster registrato

Se non conosci il nome del cluster a cui vuoi accedere, puoi vedere tutti i cluster registrati del parco risorse attuale eseguendo questo comando:

gcloud container fleet memberships list

In questo modo sono elencati tutti i cluster del parco risorse, inclusi i relativi nomi di appartenenza e ID esterni. Ogni cluster di un parco risorse ha un nome di appartenenza univoco. Per i cluster GKE, il nome dell'appartenenza corrisponde in genere al nome che hai assegnato al momento della creazione del cluster, a meno che il nome del cluster non fosse univoco all'interno del relativo progetto al momento della registrazione.

Ottieni il gateway del cluster kubeconfig

Utilizza il seguente comando per ottenere il kubeconfig di cui hai bisogno per interagire con il cluster specificato, sostituendo MEMBERSHIP_NAME con il nome dell'appartenenza al parco risorse del cluster. Questo comando restituisce uno speciale Connetti kubeconfig specifico per il gateway che ti consente di connetterti al cluster tramite il gateway.

# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Se vuoi utilizzare un account di servizio anziché il tuo account Google Cloud, usa gcloud config per impostare auth/impersonate_service_account come indirizzo email dell'account di servizio. Per saperne di più su come consentire agli utenti di impersonare un account di servizio, consulta Gestire l'accesso agli account di servizio.

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Esegui comandi sul cluster

Quando hai le credenziali necessarie, puoi eseguire i comandi utilizzando kubectl o go-client come faresti normalmente per qualsiasi cluster Kubernetes. L'output dovrebbe essere simile al seguente:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

I seguenti comandi kubectl non sono supportati dal gateway:

  • exec
  • proxy
  • port-forward
  • attach

Risoluzione dei problemi

Se hai problemi a connetterti a un cluster tramite il gateway, tu o il tuo amministratore potete verificare i seguenti problemi comuni.

  • Il server non dispone di un tipo di risorsa: potresti visualizzare questo messaggio di errore quando un comando semplice come kubectl get ns ha esito negativo. Esistono diversi potenziali motivi per questo errore. Esegui i comandi kubectl in modalità dettagliata per visualizzare maggiori dettagli, ad esempio kubectl get ns -v 10.
  • Impossibile trovare connessioni attive per il cluster(progetto: 12345, abbonamento: mio-cluster): potresti visualizzare questo errore quando l'agente Connect perde la connettività o non è installato correttamente. Per risolvere questo problema, devi verificare se lo spazio dei nomi gke-connect esiste nel cluster. In caso contrario, consulta la sezione Registrare un cluster con Google Cloud CLI. Se nel cluster esiste lo spazio dei nomi gke-connect, consulta la pagina per la risoluzione dei problemi di connessione per risolvere i problemi di connettività.
  • L'URL richiesto non è stato trovato su questo server. Puoi visualizzare questo errore quando kubeconfig contiene un indirizzo del server errato. Assicurati che la versione di Google Cloud CLI che stai utilizzando sia la versione più recente e riprova a generare il gateway kubeconfig. Non modificare manualmente il file kubeconfig, per evitare errori imprevisti.
  • L'identità utente non dispone di autorizzazioni sufficienti per utilizzare l'API gateway: per utilizzare l'API devi disporre del ruolo roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader o roles/gkehub.gatewayEditor. Per maggiori dettagli, consulta Concedi ruoli IAM agli utenti nella guida alla configurazione del gateway.
  • L'agente Connect non è autorizzato a inviare le richieste dell'utente: l'agente Connect deve essere autorizzato a inoltrare le richieste per tuo conto, operazione che viene specificata utilizzando un criterio di rappresentazione nel cluster. Consulta Configurare l'autorizzazione RBAC nella guida alla configurazione del gateway per un esempio di aggiunta di un utente al ruolo gateway-impersonate.
  • L'identità utente non dispone di autorizzazioni RBAC sufficienti per eseguire l'operazione: per eseguire le operazioni che hai scelto devi disporre delle autorizzazioni appropriate sul cluster. Consulta Configurare l'autorizzazione RBAC nella guida alla configurazione del gateway per un esempio di aggiunta di un utente all'elemento ClusterRole appropriato.
  • L'identità utente non dispone di autorizzazioni sufficienti per eseguire l'operazione quando utilizzi Google Gruppi o l'assistenza di terze parti: consulta Raccolta dei log di GKE Identity Service per istruzioni su come esaminare i log relativi alle informazioni sull'identità.
  • L'agente Connect non è integro: consulta la pagina per la risoluzione dei problemi di connessione per assicurarti che il cluster sia connesso.
  • gke-gcloud-auth-plugin non trovato o nessun provider di autenticazione trovato per il nome gcp: le versioni kubectl 1.26 e successive potrebbero visualizzare questo errore a causa di modifiche all'autenticazione kubectl a partire dalla versione 1.26 di GKE. Installa gke-gcloud-auth-plugin ed esegui di nuovo gcloud container fleet memberships get-credentials MEMBERSHIP_NAME con la versione più recente di Google Cloud CLI.
  • Le connessioni al gateway non vanno a buon fine con le versioni precedenti di Google Cloud CLI: per i cluster GKE, l'agente Connect non è più necessario per il funzionamento del gateway, quindi non viene installato per impostazione predefinita durante la registrazione dell'abbonamento. Le versioni precedenti di Google Cloud CLI (399.0.0 e versioni precedenti) presuppongono l'esistenza dell'agente Connect nel cluster. Il tentativo di utilizzare il gateway con queste versioni precedenti potrebbe non riuscire sui cluster registrati con una versione più recente di Google Cloud CLI. Per risolvere il problema, esegui l'upgrade del client Google Cloud CLI a una versione più recente o esegui nuovamente il comando di registrazione dell'abbonamento con il flag --install-connect-agent.

Che cosa succede dopo?

  • Per un esempio di come utilizzare il gateway Connect come parte dell'automazione DevOps, consulta il nostro tutorial Integrazione con Cloud Build.