Utilizzo di Connect Gateway

Questa pagina spiega come utilizzare Connect Gateway per connettersi a un cluster registrato. Prima di leggere questa guida, è necessario acquisire familiarità con 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 avere 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 vengono installati automaticamente.

  • Assicurati di aver inizializzato gcloud CLI per l'utilizzo 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 collegati tramite l'API gateway.

Segui le istruzioni riportate in Autorizzazione degli strumenti dell'interfaccia a riga di comando Google Cloud per accedere al tuo account utente. Il gateway Connect supporta l'usurpazione di identità dell'account di servizio, 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 tuo parco risorse attuale eseguendo il seguente comando:

gcloud container fleet memberships list

Vengono elencati tutti i cluster del tuo parco risorse, inclusi i relativi 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 dell'appartenenza corrisponde in genere al nome che hai assegnato al cluster durante la creazione, a meno che il nome del cluster non fosse univoco all'interno del progetto al momento della registrazione.

Ottieni il gateway del cluster kubeconfig

Utilizza il seguente comando per ottenere il token kubeconfig necessario per interagire con il cluster specificato:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Sostituisci MEMBERSHIP_NAME con il nome del parco risorse del tuo cluster.

Questo comando restituisce un kubeconfig specifico di Connect Gateway che consente di connettersi al cluster tramite Connect Gateway.

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

Per recuperare la credenziale del cluster utilizzata per interagire con Connect Gateway 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 dell'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.

Se vuoi utilizzare un account di servizio anziché il tuo account Google Cloud, utilizza gcloud config per impostare auth/impersonate_service_account sull'indirizzo email dell'account di servizio. Scopri di più su come consentire agli utenti di assumere l'identità di un account di servizio in Gestire l'accesso agli account di servizio.

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 dell'account di servizio. Per scoprire di più su come consentire agli utenti di assumere l'identità di un account di servizio, consulta Gestire l'accesso agli account di servizio.

Esegui comandi sul cluster

Una volta ottenute le credenziali necessarie, puoi eseguire 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

Limitazioni

I seguenti comandi kubectl non sono supportati dal gateway con il comando gcloud container fleet memberships get-credentials:

  • attach
  • cp
  • exec
  • port-forward

Supporto dell'anteprima per i comandi

I comandi attach, cp e exec (ma non port-forward) sono supportati con il comando beta gcloud beta container fleet memberships get-credentials. Questo comando ti consente di utilizzare una funzionalità di anteprima di Connect Gateway.

Tieni presente i seguenti requisiti:

  • GKE su Google Cloud non è supportato nell'anteprima.

  • I cluster devono essere aggiornati alla versione 1.30 o successiva.

  • Il client kubectl deve essere nella versione 1.29 o successiva. Se utilizzi la versione 1.29, devi impostare la seguente variabile di ambiente:

    export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

    Le versioni 1.30 e successive di kubectl non richiedono la variabile di ambiente.

    Per controllare la versione del client, controlla l'output del comando kubectl version. Per installare una versione più recente di kubectl, consulta Installare gli strumenti.

Gli utenti e gli account di servizio con il ruolo IAM roles/gkehub.gatewayAdmin e cluster-admin ClusterRole dispongono delle autorizzazioni necessarie per eseguire i comandi attach, cp e exec. Se agli utenti e agli account di servizio è stato concesso un ruolo IAM personalizzato o un ruolo RBAC personalizzato, potresti dover concedere autorizzazioni aggiuntive. Per ulteriori informazioni, consulta le sezioni seguenti.

Concedi un'autorizzazione aggiuntiva, se necessario

L'autorizzazione IAM gkehub.gateway.stream è obbligatoria per eseguire i comandi attach, cp e exec tramite il gateway Connect. Questa permissione è inclusa in roles/gkehub.gatewayAdmin.

Per gli utenti che non sono proprietari del progetto o per gli utenti o gli account di servizio a cui non è stato concesso roles/gkehub.gatewayAdmin nel progetto, devi concedere roles/gkehub.gatewayAdmin o creare un ruolo personalizzato che includa gli altri ruoli richiesti e l'autorizzazione gkehub.gateway.stream. Per informazioni su come creare un ruolo personalizzato, consulta Creare e gestire i ruoli personalizzati nella documentazione IAM.

Crea e applica criteri RBAC aggiuntivi, se necessario

Gli utenti e gli account di servizio con il ruolo cluster-admin ClusterRole dispongono delle autorizzazioni necessarie per eseguire i comandi attach, cp e exec.

Per eseguire i comandi sono necessarie almeno le seguenti regole:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach"]
  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: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

Risoluzione dei problemi relativi a kubectl exec/cp/attach

L'errore restituito dall'esecuzione del comando spesso non è sufficientemente chiaro per eseguire il debug del problema. In questo caso, esegui di nuovo il comando con un livello di logging più dettagliato, ad esempio kubectl exec -v 5 ....

Il canale beta di Connect Gateway non è in uso

Se ricevi un errore 400 Bad Request, rigenera il file kubeconfig del gateway di connessione utilizzando il canale beta gcloud CLI per verificare se l'errore viene corretto:

gcloud beta container fleet memberships get-credentials my-membership`

Se l'errore 400 Bad Request persiste, segui i passaggi indicati nella sezione successiva.

Il flag dell'ambiente kubectl non è impostato

Se la versione del client kubectl in uso è 1.29, la variabile di ambiente KUBECTL_REMOTE_COMMAND_WEBSOCKETS deve essere attivata. Se questa opzione non è attivata, viene visualizzato un errore 400 Bad Request. Per verificare se la variabile di ambiente è abilitata, esegui il seguente comando:

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

Se la variabile non è impostata, attivala impostando la seguente variabile di ambiente:

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

kubectl versione 1.30 e successive non richiede questo flag perché è attivato per impostazione predefinita.

La versione di kubectl precedente alla 1.29 non funziona con questa funzionalità.

Autorizzazioni IAM mancanti

Se ricevi il messaggio error: error reading from error stream..., potrebbe indicare che non ti sono state concesse le autorizzazioni IAM necessarie per eseguire il comando. Questa funzionalità richiede agli utenti di disporre dell'autorizzazione IAM gkehub.gateway.stream, inclusa per impostazione predefinita nel ruolo roles/gkehub.gatewayAdmin. Per istruzioni, consulta la sezione sulle autorizzazioni IAM.

Messaggio di errore generic::failed_precondition: errore rilevato all'interno del cluster

Se ricevi l'errore generic::failed_precondition: error encountered within the cluster, controlla i log di Connect Agent nel cluster per identificare la causa di fondo:

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....

Mancano le autorizzazioni RBAC richieste

Se il messaggio di errore nei log di Connect Agent contiene 403 Forbidden, indica che mancano le autorizzazioni RBAC. Nel cluster hai un insieme di autorizzazioni RBAC per eseguire questi comandi kubectl. Consulta la sezione Criteri RBAC per configurare le autorizzazioni RBAC richieste.

Messaggio di errore generic::resource_exhausted: quota active_streams del gateway esaurita

Esiste un limite di quota di 10 stream attivi per progetto host del parco risorse. Questo valore è definito in base alla quota connectgateway.googleapis.com/active_streams. Per istruzioni su come gestire le quote, consulta Visualizzare e gestire le quote.

Messaggio di errore generic::failed_precondition: connessione all'agente non riuscita/interrotta

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

Se si verifica questo errore dopo circa 5-10 minuti dall'attivazione della sessione, si tratta di una limitazione prevista della funzionalità. È necessario ristabilire la connessione.

Risoluzione dei problemi

Se hai problemi a connetterti 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 va a buon fine. Esistono diversi potenziali motivi per questo errore. Esegui i comandi kubectl in modalità dettagliata per visualizzare ulteriori dettagli, ad esempio kubectl get ns -v 10.
  • Cannot find active connections for cluster(project: 12345, membership: my-cluster): potresti visualizzare questo errore quando Connect Agent perde la connettività o non è installato correttamente (solo cluster esterni a 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 connessione per risolvere i problemi di connettività.
  • Impossibile trovare l'URL richiesto su questo server: potresti visualizzare questo errore quando kubeconfig contiene un indirizzo server errato. Assicurati di utilizzare la versione più recente di Google Cloud CLI e riprova a generare il gateway kubeconfig. Non modificare manualmente il file kubeconfig, altrimenti si verificheranno errori imprevisti.
  • L'identità utente non dispone delle 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 ulteriori dettagli, consulta la sezione Concedere 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 avere l'autorizzazione a inoltrare le richieste per tuo conto, che viene specificata utilizzando un criterio di furto d'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 a ClusterRole appropriato, consulta Configurare l'autorizzazione RBAC nella guida alla configurazione del gateway.
  • L'identità utente non dispone delle autorizzazioni sufficienti per eseguire l'operazione quando si utilizza Google Gruppi o l'assistenza di terze parti: consulta la sezione Raccolta dei log di GKE Identity Service per istruzioni su come ispezionare i log relativi alle informazioni sull'identità.
  • L'agente Connect non è in stato operativo: consulta la pagina Risoluzione dei problemi di Connect per assicurarti che il cluster sia connesso.
  • Executable gke-gcloud-auth-plugin not found o No Auth Provider found for name gcp: le versioni di kubectl 1.26 e successive potrebbero mostrare questo errore a causa delle modifiche all'autenticazione di kubectl a partire da GKE 1.26. 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 riescono con le versioni precedenti di Google Cloud CLI: per i cluster GKE, l'agente Connect non è più necessario per il funzionamento del gateway, pertanto non viene installato per impostazione predefinita durante la registrazione dell'abbonamento. Le versioni precedenti di Google Cloud CLI (399.0.0 e precedenti) presuppongono l'esistenza dell'agente Connect nel cluster. Il tentativo di utilizzare il gateway con queste versioni precedenti potrebbe non riuscire nei 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 all'abbonamento con il flag --install-connect-agent.

Passaggi successivi

  • Consulta un esempio di come utilizzare il gateway Connect nell'ambito dell'automazione DevOps nel nostro tutorial sull'integrazione con Cloud Build.