In questa pagina viene spiegato come installare e configurare lo strumento a riga di comando kubectl
.
e come risolvere i problemi
di configurazione più comuni.
Questa pagina è rivolta agli amministratori IT, agli operatori e Gli sviluppatori che configurano, monitorano e gestiscono l'infrastruttura cloud, nonché il provisioning e la configurazione delle risorse cloud. Per scoprire di più sui ruoli comuni e ad esempio di attività a cui facciamo riferimento nei contenuti di Google Cloud, Ruoli e attività utente comuni di GKE Enterprise.
Panoramica
kubectl
è uno strumento a riga di comando che puoi usare per interagire con GKE
cluster. Per utilizzare kubectl
con GKE, devi installare lo strumento e configurarlo
per comunicare con i tuoi cluster. Se è necessaria un'ulteriore configurazione di kubectl
per eseguire più cluster in Google Cloud.
In questa pagina vengono visualizzate le seguenti informazioni:
- Come funziona l'
kubectl
. - Come installare
kubectl
ed eventuali dipendenze richieste. - Scopri come impostare un cluster predefinito per
kubectl
. - Come eseguire comandi
kubectl
su un cluster specifico.
Prima di iniziare
Prima di iniziare, assicurati di aver eseguito le seguenti attività:
- Attiva l'API Google Kubernetes Engine. Abilita l'API Google Kubernetes Engine .
- Se vuoi utilizzare Google Cloud CLI per questa attività,
install e poi
inizializzare
con gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente
eseguendo
gcloud components update
.
Installa kubectl
Puoi installare kubectl
utilizzando Google Cloud CLI o un pacchetto esterno
amministratore come apt
o yum
.
gcloud
Installa il componente
kubectl
:gcloud components install kubectl
Verifica che
kubectl
sia installato controllando che sia aggiornata all'ultima versione:kubectl version --client
apt
Verifica di avere il repository
cloud-sdk
:grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
L'output è simile al seguente:
deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main
Se il repository
cloud-sdk
non è in elenco, installa gcloud CLI.Installa il componente
kubectl
:apt-get update apt-get install -y kubectl
Verifica che
kubectl
sia installato controllando che sia aggiornata all'ultima versione:kubectl version --client
slurp
Verifica di avere il repository
cloud-sdk
:yum repolist | grep "google-cloud-sdk"
L'output è simile al seguente:
google-cloud-sdk Google Cloud SDK 2,205
Installa il componente
kubectl
:yum install -y kubectl
Verifica che
kubectl
sia installato controllando che sia aggiornata all'ultima versione:kubectl version --client
Installa i plug-in richiesti
kubectl
e altri client Kubernetes richiedono un plug-in di autenticazione,
gke-gcloud-auth-plugin
, che utilizza il parametro
il framework plug-in delle credenziali Client-go per
forniscono token di autenticazione per comunicare con i cluster GKE.
Prima del rilascio della versione 1.26 di Kubernetes, gcloud CLI avvia
per richiedere l'installazione del programma binario gke-gcloud-auth-plugin
. In caso contrario
installazioni esistenti di kubectl
o di altri client Kubernetes personalizzati
smetterà di funzionare.
Devi
installa questo plug-in per utilizzare kubectl
e altri client per interagire con GKE.
Se il plug-in non è installato, i client esistenti visualizzano un messaggio di errore.
Prima di iniziare, controlla se il plug-in è già installato:
gke-gcloud-auth-plugin --version
Se l'output mostra informazioni sulla versione, salta questa sezione.
Puoi installare il plug-in di autenticazione utilizzando gcloud CLI o un
gestore di pacchetti esterno come apt
o yum
.
gcloud
Installa il programma binario gke-gcloud-auth-plugin
:
gcloud components install gke-gcloud-auth-plugin
apt
Installa il programma binario gke-gcloud-auth-plugin
:
apt-get install google-cloud-sdk-gke-gcloud-auth-plugin
slurp
Installa il programma binario gke-gcloud-auth-plugin
:
yum install google-cloud-sdk-gke-gcloud-auth-plugin
Verifica l'installazione del programma binario gke-gcloud-auth-plugin
:
Controlla la versione binaria di
gke-gcloud-auth-plugin
:gke-gcloud-auth-plugin --version
Aggiorna la configurazione
kubectl
per utilizzare il plug-in:gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Sostituisci quanto segue:
CLUSTER_NAME
: il nome del tuo cluster.COMPUTE_REGION
: il Compute Engine region per il tuo cluster. Per cluster di zona, usa--zone=COMPUTE_ZONE
.
Verifica la configurazione:
kubectl get namespaces
L'output è simile al seguente:
NAME STATUS AGE default Active 51d kube-node-lease Active 51d kube-public Active 51d kube-system Active 51d
Per ulteriori informazioni sul motivo per cui questo plug-in è richiesto, consulta Kubernetes KEP.
Interagisci con kubectl
Kubernetes usa un file YAML
kubeconfig
per archiviare le informazioni di autenticazione del cluster per kubectl
. Per impostazione predefinita,
il file viene salvato alle ore $HOME/.kube/config
.
kubeconfig
contiene un gruppo di parametri di accesso chiamati contesti. Ogni contesto contiene un modello
un cluster, un utente e uno spazio dei nomi predefinito facoltativo. kubectl
si riferisce ai contesti quando vengono eseguiti i comandi.
Di seguito sono riportate le attività che puoi completare per configurare kubectl
:
- Scegli il cluster con cui comunica
kubectl
. - Imposta un cluster predefinito per
kubectl
impostando il contesto attuale in il filekubeconfig
. - Esegui i comandi
kubectl
su un cluster specifico utilizzando il flag--cluster
.
Visualizza kubeconfig
Per visualizzare kubeconfig
del tuo ambiente, esegui questo comando:
kubectl config view
Il comando restituisce un elenco di tutti i cluster per i quali le voci kubeconfig
sono
sono stati generati. Se è elencato un cluster GKE, puoi eseguire kubectl
dei comandi
nel tuo ambiente attuale. In caso contrario, dovrai
Archivia le informazioni sul cluster per kubectl.
Visualizza il contesto attuale per kubectl
Il contesto attuale è il cluster attualmente predefinito
kubectl
. Tutti i comandi kubectl
vengono eseguiti sul cluster.
Quando crei un cluster utilizzando gcloud container clusters create-auto
, viene eseguita
viene aggiunta automaticamente al file kubeconfig
nel tuo ambiente e
le modifiche al contesto attuale
nel cluster. Ad esempio:
gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster
Per visualizzare il contesto attuale per kubectl
, esegui questo comando:
kubectl config current-context
Archivia le informazioni sul cluster kubectl
Quando crei un cluster utilizzando la console Google Cloud o gcloud CLI da un
computer diverso, il file kubeconfig
del tuo ambiente non viene aggiornato.
Inoltre, se un membro del team di progetto utilizza gcloud CLI per creare un cluster da
il suo computer, il suo kubeconfig
è aggiornato, mentre il tuo non lo è. kubeconfig
contiene:
- Le tue credenziali come mostrate in
gcloud auth list
; oppure - Le credenziali predefinite dell'applicazione, se configurate.
Per generare un contesto kubeconfig
nel tuo ambiente, assicurati di avere il
Autorizzazione container.clusters.get
. IAM con privilegi minimi
Il ruolo che fornisce questa autorizzazione è container.clusterViewer
.
Per generare un contesto kubeconfig
per un cluster specifico, esegui il comando
seguente comando:
gcloud container clusters get-credentials CLUSTER_NAME \
--region=CLUSTER_REGION
Sostituisci quanto segue:
CLUSTER_NAME
: il nome del tuo cluster.COMPUTE_REGION
: il Compute Engine region per il tuo cluster. Per cluster di zona, usa--zone=COMPUTE_ZONE
.
Genera una voce kubeconfig
utilizzando l'indirizzo IP interno di un cluster privato
Tutti i cluster hanno un endpoint canonico. L'endpoint espone
Server API Kubernetes che kubectl
e altri servizi utilizzano per comunicare con
dal piano di controllo del tuo cluster.
Cluster privati
avere due indirizzi IP endpoint separati: privateEndpoint
,
che è un indirizzo IP interno e publicEndpoint
, che è un indirizzo IP esterno.
Il campo endpoint
si riferisce all'indirizzo IP esterno, a meno che l'accesso pubblico al
l'endpoint è disabilitato e in questo caso verrà utilizzato l'indirizzo IP privato.
Per i cluster privati, se preferisci utilizzare l'indirizzo IP interno come esegui questo comando:
gcloud container clusters get-credentials CLUSTER_NAME --internal-ip
Sostituisci CLUSTER_NAME
con il nome del tuo cluster.
L'esecuzione di get-credentials
utilizza l'indirizzo IP specificato nel campo endpoint
per impostazione predefinita.
Imposta un cluster predefinito per i comandi kubectl
Se in precedenza hai generato una voce kubeconfig per i cluster, puoi passare
il contesto attuale per kubectl
al cluster eseguendo questo comando
:
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
Sostituisci quanto segue:
CLUSTER_NAME
: il nome del tuo cluster.COMPUTE_REGION
: il Compute Engine region per il tuo cluster. Per cluster di zona, usa--zone=COMPUTE_ZONE
.
Ad esempio, considera un progetto con due cluster, my-cluster
e
my-new-cluster
. Il contesto attuale è my-new-cluster
, ma vuoi eseguire l'operazione
tutti i comandi kubectl
rispetto a my-cluster
. Per cambiare il contesto corrente:
da my-new-cluster
a my-cluster
, esegui questo comando:
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
Esegui singoli comandi kubectl
su un cluster specifico
Puoi eseguire singoli comandi kubectl
su un cluster specifico utilizzando
--cluster=CLUSTER_NAME
.
Considera ad esempio un ambiente con due cluster, my-cluster
e
my-new-cluster
, in cui il contesto attuale è my-cluster
. Vuoi
eseguire il deployment di un'applicazione in my-new-cluster
, ma non vuoi modificare
contesto attuale. Per eseguire il deployment dell'applicazione in my-new-cluster
senza modificare
contesto corrente, dovresti eseguire questo comando:
kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster
Risoluzione dei problemi
Per ulteriori informazioni sulla risoluzione dei problemi, consulta Risoluzione dei problemi più comuni.
Ambiti di autenticazione insufficienti
Quando esegui gcloud container clusters get-credentials
ricevi quanto segue
errore:
ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.
Questo errore si verifica perché stai tentando di accedere all'API Kubernetes Engine da
una VM di Compute Engine che non ha l'ambito cloud-platform
. Per
per la modifica degli ambiti
sull'istanza VM di Compute Engine, consulta
Creazione e abilitazione degli account di servizio per le istanze.
ERRORE: eseguibile gke-gcloud-auth-plugin non trovato
Se viene visualizzato il seguente errore durante il tentativo di eseguire kubectl
o client personalizzati
interagendo con GKE, installa gke-gcloud-auth-plugin
come descritto in
Istruzioni di installazione.
I messaggi di errore sono simili ai seguenti:
- Esempio di errore
Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found
It looks like you are trying to use a client-go credential plugin that is not installed.
To learn more about this feature, consult the documentation available at:
https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.
- Esempio di errore
Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory
ERRORE: panic: nessun provider di autenticazione trovato per il nome gcp
L'errore no Auth Provider found for name "gcp"
viene ricevuto se kubectl
o personalizzato
I client Kubernetes sono stati creati con Kubernetes client-go
versione 1.26 o successive, come descritto
in Come funziona. Per risolvere il problema, procedi nel seguente modo:
Installa
gke-gcloud-auth-plugin
come descritto in Istruzioni sull'installazione.Esegui l'aggiornamento all'ultima versione di gcloud CLI utilizzando
gcloud components update
.Aggiorna il file
kubeconfig
.gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Sostituisci quanto segue:
CLUSTER_NAME
: il nome del tuo cluster.COMPUTE_REGION
: il Compute Engine region per il tuo cluster. Per cluster di zona, usa--zone=COMPUTE_ZONE
.
ATTENZIONE: il plug-in di autenticazione Google Cloud è deprecato. Utilizza gcloud
Potresti visualizzare questo messaggio di avviso dopo aver installato
gke-gcloud-auth-plugin
ed esegui un comando kubectl
su un
cluster GKE. Questo messaggio viene visualizzato se la versione client è
prima della 1:26.
Per indicare al client di utilizzare il plug-in di autenticazione gke-gcloud-auth-plugin
segui questi passaggi:
Apri lo script di accesso della shell in un editor di testo:
Bash
vi ~/.bashrc
Zsh
vi ~/.zshrc
Se utilizzi PowerShell, salta questo passaggio.
Imposta la seguente variabile di ambiente:
Bash
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
Zsh
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
PowerShell
[Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
Applica la variabile nel tuo ambiente:
Bash
source ~/.bashrc
Zsh
source ~/.zshrc
PowerShell
Esci dal terminale e apri una nuova sessione del terminale.
Aggiorna gcloud CLI:
gcloud components update
Esegui l'autenticazione nel cluster:
gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Sostituisci quanto segue:
CLUSTER_NAME
: il nome del tuo cluster.COMPUTE_REGION
: il Compute Engine region per il tuo cluster. Per cluster di zona, usa--zone=COMPUTE_ZONE
.
Passaggi successivi
- Scopri come autorizzare l'accesso alle risorse nei cluster GKE.
- Esegui l'autenticazione nei servizi Google Cloud dai carichi di lavoro GKE.
- Leggi la scheda di riferimento di
kubectl
.
Provalo
Se non hai mai utilizzato Google Cloud, crea un account per valutare in che modo GKE si comporta nel mondo reale diversi scenari. I nuovi clienti ricevono anche 300 $ di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
Prova GKE gratuitamente