Utilizzo di Connect Gateway

Questa pagina spiega come utilizzare il gateway Connect per connetterti a un cluster registrato. Prima di leggere questa pagina, assicurati di conoscere i concetti descritti nella nostra panoramica. La guida presuppone che l'amministratore del progetto abbia già configurato il gateway e ti abbia assegnato i ruoli e le autorizzazioni necessari.

Prima di iniziare

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

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

  • Assicurati di aver inizializzato gcloud CLI per l'utilizzo con il tuo progetto.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare il gateway Connect per connetterti ai cluster ed eseguire comandi, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto del cluster:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Il ruolo Amministratore del gateway Connect (roles/gkehub.gatewayAdmin) è l'unico ruolo predefinito che contiene l'autorizzazione gkehub.gateway.stream, necessaria per eseguire i comandi dell'interfaccia a riga di comando kubectl come attach, exec, port-forward e cp.

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Accedi al tuo Google Cloud account

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

Segui le istruzioni riportate in Autorizzare gli strumenti Google Cloud CLI per accedere al tuo account utente. Il gateway Connect supporta la simulazione dell'identità dei service account, quindi anche se hai eseguito l'accesso al tuo account utente puoi utilizzare un account di servizio 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 visualizzare tutti i cluster registrati del parco risorse corrente eseguendo il comando seguente:

gcloud container fleet memberships list

Vengono elencati tutti i cluster del parco risorse, inclusi i nomi di appartenenza e gli ID esterni. Ogni cluster in un parco risorse ha un nome di appartenenza univoco. Per i cluster GKE, il nome di appartenenza in genere corrisponde al nome che hai assegnato al cluster quando lo hai creato, a meno che il nome del cluster non fosse univoco all'interno del progetto al momento della registrazione.

Recupera il file kubeconfig del gateway del cluster

Utilizza il comando seguente per recuperare il file kubeconfig necessario per interagire con il cluster specificato:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Sostituisci MEMBERSHIP_NAME con il nome di appartenenza del parco risorse del cluster.

Questo comando restituisce un file kubeconfig specifico del gateway Connect che ti consente di connetterti al cluster tramite il gateway Connect.

Se vuoi utilizzare un account di servizio anziché il tuo Google Cloud account, utilizza gcloud config per impostare auth/impersonate_service_account sull'indirizzo email dell'account del service account.

Per recuperare le credenziali del cluster utilizzate per interagire con il gateway Connect utilizzando un account di servizio, esegui i seguenti comandi: Tieni presente quanto segue:

  • Cluster Google Distributed Cloud (solo software) su bare metal e VMware: il nome di appartenenza è uguale al nome del cluster.

  • GKE su AWS: utilizza gcloud container aws clusters get-credentials.

  • GKE su Azure: utilizza gcloud container azure clusters get-credentials.

Puoi scoprire di più su come consentire agli utenti di assumere l'identità di un account di servizio in Gestisci l'accesso ai service account.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Sostituisci SA_EMAIL_ADDRESS con l'indirizzo email del account di servizio. Puoi scoprire di più su come consentire agli utenti di assumere l'identità di un service account in Gestisci l'accesso ai service account.

Esegui comandi sul cluster

Una volta che hai le credenziali necessarie, puoi eseguire i comandi utilizzando kubectl o un 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

Comandi kubectl exec/cp/attach/port-forward

I seguenti comandi kubectl sono comandi di streaming e hanno requisiti aggiuntivi:

  • attach
  • cp
  • exec
  • port-forward

Per eseguire questi comandi, devi soddisfare i seguenti requisiti:

  • I cluster devono essere alla versione 1.30 o successive per i comandi attach, cp ed exec e alla versione 1.31 o successive per il comando port-forward.

  • Il client kubectl deve essere alla versione 1.31 o successive. Per controllare la versione del client, esamina l'output del comando kubectl version. Per installare una versione più recente di kubectl, consulta Installare gli strumenti.

  • Gli utenti e i service account devono disporre del seguente accesso aggiuntivo all'API Kubernetes tramite IAM o RBAC:

    • IAM: concedi un ruolo che includa l'autorizzazione gkehub.gateway.stream. Il ruolo predefinito roles/gkehub.gatewayAdmin include questa autorizzazione. Puoi anche assegnare questa autorizzazione a un ruolo personalizzato.

    • RBAC: concedi un ruolo o un ClusterRole che includa l'accesso get alle sottorisorse API pods/exec, pods/portforward e pods/attach, come in nel seguente esempio di ruolo e RoleBinding:

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE # Specify the namespace
roleRef:
  apiGroup: "rbac.authorization.k8s.io"
  kind: Role
  name: stream-role
subjects:
- kind: Group
  name: EMAIL # Specify the group that should have stream access

      Sostituisci quanto segue:

      • NAMESPACE: lo spazio dei nomi per il ruolo e il RoleBinding.
      • EMAIL: l'indirizzo email del gruppo che deve avere l'accesso allo stream, se il cluster supporta RBAC con i gruppi.

      Il ClusterRole predefinito cluster-admin include anche queste autorizzazioni.

Risoluzione dei problemi

Se hai problemi di connessione a un cluster tramite il gateway, tu o il tuo amministratore potete verificare la presenza dei seguenti problemi comuni.

  • Il server non ha un tipo di risorsa: potresti visualizzare questo messaggio di errore quando il comando kubectl get ns non riesce. Esistono diversi motivi potenziali 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, appartenenza: my-cluster): potresti visualizzare questo errore quando l'agente Connect perde la connettività o non è installato correttamente (solo cluster esterni Google Cloud ). Per risolvere il problema, devi verificare se lo spazio dei nomi gke-connect esiste nel cluster. Se lo spazio dei nomi gke-connect esiste nel cluster, consulta la pagina Risoluzione dei problemi di Connect per risolvere i problemi di connettività.
  • Impossibile trovare l'URL richiesto su questo server: potresti visualizzare questo errore quando il file 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, perché ciò causerebbe 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 Concedere i 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, come specificato utilizzando un criterio di assunzione dell'identità sul cluster. Per un esempio di aggiunta di un utente al ruolo gateway-impersonate, consulta Configurare l'autorizzazione RBAC nella guida alla configurazione del gateway.
  • L'identità utente non dispone di autorizzazioni RBAC sufficienti per eseguire l'operazione: devi disporre delle autorizzazioni appropriate sul cluster per eseguire le operazioni scelte. Per un esempio di aggiunta di un utente al ClusterRole appropriato, consulta Configurare l'autorizzazione RBAC nella guida alla configurazione del gateway.
  • L'identità utente non dispone di autorizzazioni sufficienti per eseguire l'operazione quando si utilizzano Google Gruppi o l'assistenza di terze parti: per istruzioni su come esaminare i log relativi alle informazioni sull'identità, consulta Raccogliere i log del GKE Identity Service.
  • L'agente Connect non è integro: consulta la pagina Risoluzione dei problemi di Connect per assicurarti che il cluster sia connesso.
  • Eseguibile gke-gcloud-auth-plugin non trovato o Nessun provider di autenticazione trovato per il nome gcp: le versioni di kubectl 1.26 e successive potrebbero visualizzare questo errore a causa delle modifiche all'autenticazione kubectl a partire da GKE v1.26. Installa gke-gcloud-auth-plugin ed esegui di nuovo gcloud container fleet memberships get-credentials MEMBERSHIP_NAME con l'ultima versione di Google Cloud CLI.
  • Le connessioni al gateway non riescono 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'appartenenza. Le versioni precedenti di Google Cloud CLI (399.0.0 e precedenti) presuppongono l'esistenza dell'agente Connect sul 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 di nuovo il comando di registrazione dell'appartenenza con il flag --install-connect-agent.
  • Le dimensioni dei gruppi restituiti nel gruppo gke-security-groups superano il limite di dimensioni dell'intestazione HTTP di 8 KB. Riorganizza la gerarchia dei gruppi e riprova: anche se non esiste un limite rigido al numero di gruppi, i nomi dei gruppi lunghi possono far sì che la richiesta superi il limite di dimensioni dell'intestazione HTTP di 8 KB e generi errori che potrebbero richiedere la ristrutturazione della gerarchia dei gruppi.

Risoluzione dei problemi relativi a kubectl exec/cp/attach/port-forward

L'errore restituito dall'esecuzione del comando è spesso un errore generico 400 Bad Request, che non è abbastanza chiaro per eseguire il debug del problema. Per restituire messaggi di errore più dettagliati, utilizza la versione del client kubectl 1.32 o successive per eseguire il comando con un livello di verbosità pari a 4 o superiore, ad esempio: kubectl exec -v 4 ....

Nei log restituiti, cerca il log che contiene le seguenti risposte:

  • Per il comando kubectl exec/cp/attach: RemoteCommand fallback:
  • Per il comando kubectl port-forward: fallback to secondary dialer from primary dialer err:

Per la risoluzione dei problemi relativi ad alcuni dei messaggi di errore comuni che potresti ricevere dal comando kubectl exec -v 4 ..., consulta la sezione seguente.

Autorizzazioni IAM mancanti

Se il messaggio di errore contiene generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, questo potrebbe indicare che non ti sono state concesse le autorizzazioni IAM necessarie per eseguire il comando. Questa funzionalità richiede che gli utenti dispongano dell'autorizzazione IAM gkehub.gateway.stream, inclusa per impostazione predefinita nel ruolo roles/gkehub.gatewayAdmin. Per istruzioni, consulta la sezione Autorizzazioni IAM.

Autorizzazioni RBAC obbligatorie mancanti

Se il messaggio di errore contiene ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., indica che mancano le autorizzazioni RBAC. Per eseguire questi comandi kubectl, devi disporre di un insieme di autorizzazioni RBAC nel cluster. Per ulteriori informazioni sulla configurazione delle autorizzazioni RBAC richieste, consulta Creare e applicare policy RBAC aggiuntive, se necessario.

Messaggio di errore generic::resource_exhausted: Gateway's active_streams quota exhausted

Esiste un limite di quota di 10 stream attivi per progetto host del parco risorse. Questo limite è definito nella quota connectgateway.googleapis.com/active_streams. Per istruzioni sulla gestione delle quote, consulta Visualizza e gestisci le quote.

Messaggio di errore generic::failed_precondition: error encountered within the cluster

Se viene visualizzato l'errore generic::failed_precondition: error encountered within the cluster, controlla i log dell'agente Connect nel cluster per identificare la causa sottostante:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Il log da cercare nell'agente Connect è failed to create the websocket connection....

Messaggio di errore generic::failed_precondition: connection to Agent failed/terminated

Se visualizzi questo errore immediatamente dopo aver eseguito il comando, si è verificato un problema con la connessione del cluster a Google. Per ulteriori informazioni, consulta la guida generale alla risoluzione dei problemi.

Se visualizzi questo errore dopo che la sessione è attiva per circa 20-30 minuti, si tratta di una limitazione prevista per motivi di sicurezza. È necessario ristabilire la connessione.

Risoluzione dei problemi relativi a kubectl --raw

L'utilizzo di un endpoint abbreviato (ad esempio kubectl get --raw /version) potrebbe generare il seguente errore: Error from server (NotFound): the server could not find the requested resource. Devi fornire l'indirizzo completo del server.

Recupera l'endpoint dal file kubeconfig:

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

Quindi utilizza l'endpoint per il comando, ad esempio con /version:

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

Passaggi successivi

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