Utilizzo di Connect Gateway
Questa pagina spiega come utilizzare il gateway Connect per connettersi a un cluster registrato. Prima di leggere questa guida, dovresti conoscere i concetti esposti nella nostra panoramica. La guida presuppone che l'amministratore del progetto abbia già configurato il gateway e ti abbia concesso i ruoli e le autorizzazioni necessari.
Prima di iniziare
Assicurati di avere 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 sono installati automaticamente.
Assicurati di aver inizializzato la gcloud CLI da utilizzare 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 riportate in Autorizzazione degli strumenti dell'interfaccia a riga di comando Google Cloud per accedere al tuo account utente. Il gateway Connect supporta la rappresentazione degli 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 illustrato 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 questo comando:
gcloud container fleet memberships list
Questo elenco include 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 dell'appartenenza in genere corrisponde al nome che gli hai assegnato quando hai creato il cluster, a meno che il nome del cluster non fosse univoco all'interno del progetto al momento della registrazione.
Ottieni il gateway del cluster kubeconfig
Usa questo comando per ottenere il kubeconfig
di cui hai bisogno per interagire con il tuo
cluster specificato:
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
Sostituisci MEMBERSHIP_NAME
con l'abbonamento al parco risorse del cluster
nome.
Questo comando restituisce uno speciale Connect gateway-specific kubeconfig
che
consente di connetterti al cluster tramite il gateway Connect.
Se vuoi utilizzare un account di servizio anziché il tuo account Google Cloud,
usa gcloud config
per impostare auth/impersonate_service_account
sul servizio
l'indirizzo email dell'account.
Per recuperare la credenziale del cluster utilizzata per interagire con il gateway Connect utilizzando un account di servizio, esegui questi comandi: Tieni presente quanto segue:
- Google Distributed Cloud (solo software) su bare metal e VMware: il nome dell'appartenenza è uguale al nome del cluster.
GKE su AWS: utilizzo
gcloud container aws clusters get-credentials
.GKE su Azure: usare
gcloud container azure clusters get-credentials
.
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 saperne di più su come consentire agli utenti di impersonare un account di servizio, consulta 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 del
l'account di servizio. Scopri di più su come consentire agli utenti di impersonare un servizio
in Gestire l'accesso agli account di servizio.
Esegui comandi sul cluster
Una volta in possesso delle credenziali necessarie, puoi eseguire i comandi utilizzando kubectl
o go-client
, come faresti normalmente per qualsiasi cluster Kubernetes. Dovresti vedere un output 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
utilizzando il comando gcloud container fleet memberships get-credentials
:
attach
cp
exec
port-forward
Visualizza l'anteprima del supporto per i comandi
Sono supportati i comandi attach
, cp
e exec
(ma non port-forward
)
con il comando beta gcloud beta container fleet memberships get-credentials
.
Questo comando ti consente di utilizzare
preview del gateway Connect.
Tieni presente i seguenti requisiti:
GKE su Google Cloud non è supportato nell'anteprima.
La versione dei cluster deve essere 1.30 o successiva.
Il client
kubectl
deve essere alla versione 1.29 o successive. 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 verificare la versione del client, osserva l'output del Comando
kubectl version
. Per installare una versione più recente dikubectl
consulta la sezione Strumenti di installazione.
Utenti e account di servizio con roles/gkehub.gatewayAdmin
Il ruolo IAM e i cluster-admin
ClusterRole
hanno
le autorizzazioni necessarie per eseguire i comandi attach
, cp
e exec
. Se gli utenti
e agli account di servizio sia stato concesso
un ruolo IAM personalizzato oppure
ruolo RBAC personalizzato, potrebbe essere necessario concedere autorizzazioni aggiuntive. Consulta le
le sezioni seguenti per ulteriori informazioni.
Se necessario, concedi un'autorizzazione aggiuntiva
Per eseguire è necessaria l'autorizzazione IAM gkehub.gateway.stream
i comandi attach
, cp
e exec
tramite il gateway Connect. Questo
è inclusa in roles/gkehub.gatewayAdmin
.
Per gli utenti che non sono proprietari del progetto o per gli utenti o gli account di servizio che
non hanno ricevuto roles/gkehub.gatewayAdmin
nel progetto, devi
concedigli roles/gkehub.gatewayAdmin
o crea un ruolo personalizzato
include gli altri ruoli obbligatori e gkehub.gateway.stream
autorizzazione. Per informazioni su come creare un ruolo personalizzato, consulta
Crea e gestisci ruoli personalizzati nel
documentazione di IAM.
Crea e applica criteri RBAC aggiuntivi, se necessario
Gli utenti e gli account di servizio con cluster-admin
ClusterRole
hanno lo
le 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 di kubectl exec/cp/attach
L'errore restituito dall'esecuzione del comando spesso non è abbastanza chiaro per il debug
risolvere il problema. In questo caso, esegui nuovamente il comando con un logging con livello di dettaglio più elevato
livello, ad esempio: kubectl exec -v 5 ...
.
Il canale beta Connect gateway non viene utilizzato
Se ricevi un errore 400 Bad Request
, rigenera il gateway di connessione
kubeconfig utilizzando la versione beta di gcloud CLI per vedere
corregge l'errore:
gcloud beta container fleet memberships get-credentials my-membership`
Se continui a visualizzare l'errore 400 Bad Request
, segui la procedura indicata nella
sezione successiva.
Il flag dell'ambiente kubectl non è impostato
Se la versione del client kubectl che stai utilizzando è 1.29, l'ambiente
la variabile KUBECTL_REMOTE_COMMAND_WEBSOCKETS
deve essere abilitata. Se non è
attivata, viene visualizzato l'errore 400 Bad Request
. Per vedere se la variabile di ambiente
sia abilitato, esegui questo comando:
echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`
Se la variabile non è impostata, abilitala impostando il seguente ambiente variabile:
export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
kubectl 1.30 e versioni successive non richiede questo flag perché è abilitato da predefinito.
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...
, significa che
potrebbe indicare che non ti è stato concesso
la licenza IAM richiesta
le autorizzazioni necessarie per eseguire il comando. Questa funzione richiede agli utenti di disporre
gkehub.gateway.stream
autorizzazione IAM,
che è incluso per impostazione predefinita nel ruolo roles/gkehub.gatewayAdmin
. Consulta le
Sezione Autorizzazioni IAM per le istruzioni.
Messaggio di errore generico::failed_precondition: errore riscontrato all'interno del cluster
Se viene visualizzato l'errore generic::failed_precondition: error encountered within
the cluster
, controlla i log dell'agente Connect nel cluster per identificare
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...
.
Autorizzazioni RBAC obbligatorie mancanti
Se il messaggio di errore nei log di Connect Agent contiene 403 Forbidden
,
questo indica che non hai le autorizzazioni RBAC. Disponi di un insieme di RBAC
autorizzazioni nel cluster per eseguire questi comandi kubectl.
Consulta le
Sezione Criteri RBAC
per configurare le autorizzazioni RBAC richieste.
Messaggio di errore generico::resource_exhausted: quota active_streams del gateway esaurita
Esiste un limite di quota di 10 flussi attivi per progetto host del parco risorse. Questo è
definiti nella quota connectgateway.googleapis.com/active_streams
. Consulta:
Visualizza e gestisci le quote per istruzioni sulla gestione
le tue quote.
Messaggio di errore generico::failed_precondition: connessione all'agente non riuscita/terminata
Se riscontri questo errore immediatamente durante l'esecuzione del comando, significa che problema con la connessione del cluster a Google. Consulta le informazioni generali guida alla risoluzione dei problemi per ulteriori informazioni.
Se si verifica questo errore dopo circa 5-10 minuti dal di sessione attiva, si tratta di una limitazione prevista della funzionalità. La connessione deve essere ristabilita.
Risoluzione dei problemi
Se riscontri problemi durante la connessione 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 in caso di errore del comando
kubectl get ns
. Esistono diversi possibili motivi alla base di 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 l'agente Connect perde la connettività o non è installato correttamente (solo cluster esterni a Google Cloud). Per risolvere il problema, devi verificare se nel cluster esiste lo spazio dei nomi
gke-connect
. Se lo spazio dei nomigke-connect
esiste nel cluster, consulta la pagina Risoluzione dei problemi di connessione per risolvere i problemi di connettività. - L'URL richiesto non è stato trovato su questo server. Potresti visualizzare questo errore quando
kubeconfig
contiene un indirizzo del server non corretto. Assicurati che la versione di Google Cloud CLI che stai utilizzando sia quella più recente e riprova a generare il gatewaykubeconfig
. Non modificare manualmente il filekubeconfig
, perché causerà 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 ulteriori dettagli, consulta 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. 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 scelte, 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 al
ClusterRole
appropriato. - L'identità utente non dispone di autorizzazioni sufficienti per eseguire l'operazione quando si 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 Risoluzione dei problemi di connessione per assicurarti che il cluster sia connesso.
- eseguibile gke-gcloud-auth-plugin non trovato o nessun provider di autenticazione trovato per il nome gcp: kubectl 1.26 e versioni successive potrebbero visualizzare questo errore a causa di 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 vanno a buon fine con 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
.
Passaggi successivi
- Per un esempio di come utilizzare il gateway Connect come parte dell'automazione DevOps, consulta il nostro tutorial Integrazione con Cloud Build.