Utilizzo di Connect Gateway
Questa pagina spiega come utilizzare Connect Gateway per connettersi 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:
- L'ultima versione 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 Google Cloud service account per interagire con i cluster connessi tramite l'API Gateway.
Segui le istruzioni riportate in Autorizzazione degli strumenti Google Cloud CLI per accedere al tuo account utente. Il gateway Connect supporta l'impersonificazione 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 parco risorse attuale eseguendo il seguente comando:
gcloud container fleet memberships list
Vengono elencati tutti i cluster del parco risorse, inclusi i relativi nomi di appartenenza e ID esterni. Ogni cluster in un parco risorse ha un nome di appartenenza univoco. Per i cluster GKE, il nome dell'appartenenza in genere corrisponde al nome che hai assegnato al cluster quando l'hai creato, a meno che il nome del cluster non fosse univoco all'interno del progetto al momento della registrazione.
Recupera il gateway del cluster kubeconfig
Utilizza il seguente comando per ottenere kubeconfig
necessario per interagire con il cluster specificato:
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
Sostituisci MEMBERSHIP_NAME
con il nome dell'appartenenza al parco risorse del tuo cluster.
Questo comando restituisce un kubeconfig
specifico per Connect Gateway che
ti consente di connetterti al cluster tramite Connect Gateway.
Se vuoi utilizzare un account di servizio anziché il tuo account, utilizza gcloud config
per impostare auth/impersonate_service_account
sull'indirizzo email del service account. Google Cloud
Per recuperare le credenziali del cluster utilizzate per interagire con Connect Gateway utilizzando unaccount di serviziot, esegui i seguenti comandi: Tieni presente quanto segue:
- Cluster Google Distributed Cloud (solo software) su bare metal e VMware: il nome del gruppo è 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
.
Per scoprire di più su come consentire agli utenti di assumere l'identità di un account di servizio, consulta Gestire 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 serviziot. Per saperne di più su come consentire agli utenti di assumere l'identità di un service account, consulta Gestire l'accesso ai service account.
Esegui comandi sul cluster
Una volta ottenute 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
Tieni presente i seguenti requisiti:
I cluster devono essere alla versione 1.30 o successive per i comandi
attach
,cp
eexec
e alla versione 1.31 o successive per il comandoport-forward
.Il client
kubectl
deve essere alla versione 1.31 o successiva.Per controllare la versione del client, esamina l'output del comando
kubectl version
. Per installare una versione più recente dikubectl
, vedi 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
, exec
e port-forward
. Se agli utenti e ai service account è stato concesso un ruolo IAM personalizzato o un ruolo RBAC personalizzato, potrebbe essere necessario concedere autorizzazioni aggiuntive. Per ulteriori informazioni, consulta le sezioni seguenti.
Concedi un'autorizzazione aggiuntiva, se necessario
L'autorizzazione IAM gkehub.gateway.stream
è necessaria per eseguire i comandi attach
, cp
, exec
e port-forward
tramite il gateway Connect. Questa
autorizzazione è inclusa in roles/gkehub.gatewayAdmin
.
Per gli utenti che non sono proprietari del progetto o per gli utenti o i service account 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, vedi
Creare e gestire ruoli personalizzati nella
documentazione di IAM.
Crea e applica ulteriori policy RBAC, se necessario
Gli utenti e i service account con il ruolo cluster-admin
ClusterRole
dispongono delle autorizzazioni necessarie per eseguire i comandi attach
, cp
, exec
e port-forward
.
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", "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: User
name: EMAIL # Specify the user that should have stream access
namespace: NAMESPACE # Specify the namespace
Risoluzione dei problemi
Se riscontri 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 va a buon fine. Esistono diversi motivi potenziali per questo errore. Esegui i comandikubectl
in modalità dettagliata per visualizzare maggiori dettagli, ad esempiokubectl get ns -v 10
. - Impossibile trovare connessioni attive per il cluster(progetto: 12345, appartenenza: 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 nomigke-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 del server errato. Assicurati che la versione di Google Cloud CLI che stai utilizzando sia l'ultima versione e riprova a generare il gatewaykubeconfig
. Non modificare manualmente il filekubeconfig
, altrimenti si verificheranno 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
oroles/gkehub.gatewayEditor
. Per maggiori dettagli, vedi 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 essere autorizzato a inoltrare le richieste per tuo conto, il che viene specificato utilizzando un criterio di rappresentazione 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 utilizza 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 di 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 kubectl a partire da GKE v1.26. Installa
gke-gcloud-auth-plugin
ed esegui di nuovogcloud 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, pertanto non viene installato per impostazione predefinita durante la registrazione dell'appartenenza. Le versioni precedenti della 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
.La dimensione dei gruppi restituiti nel gruppo
gke-security-groups
supera il limite di 8 KB per le dimensioni dell'intestazione HTTP. Riorganizza la gerarchia dei gruppi e riprova: anche se non esiste un limite rigido al numero di gruppi, i nomi dei gruppi lunghi possono causare il superamento del limite di dimensione dell'intestazione HTTP di 8 KB e generare 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 400 Bad Request
generico che non è abbastanza chiaro per eseguire il debug del problema. Per restituire messaggi di errore più dettagliati, utilizza la versione 1.32 o successive del client kubectl
per eseguire il comando con un livello di dettaglio pari a 4 o superiore, ad esempio:
kubectl exec -v 4 ...
.
Nei log restituiti, cerca quello 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 risolvere i 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
,
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
, che è inclusa per impostazione predefinita nel ruolo roles/gkehub.gatewayAdmin
. Per istruzioni, consulta la
sezione sulle 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...
, significa che ti 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 ulteriori norme RBAC, 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 è
definito nella quota connectgateway.googleapis.com/active_streams
. Consulta
Visualizzare e gestire le quote per istruzioni sulla gestione
delle quote.
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 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 si verifica questo errore immediatamente dopo l'esecuzione del comando, si è verificato un problema con la connessione del cluster a Google. Per ulteriori informazioni, consulta la guida generale alla risoluzione dei problemi.
Se riscontri questo errore dopo che la sessione è attiva per circa 20-30 minuti, si tratta di una limitazione prevista per motivi di sicurezza. La connessione deve essere ristabilita.
Passaggi successivi
- Consulta un esempio di come utilizzare il gateway Connect nell'ambito dell'automazione DevOps nel nostro tutorial Integrazione con Cloud Build.