Installa kubectl e configura l'accesso al cluster

Questa pagina spiega come installare e configurare lo strumento a riga di comando kubectl per interagire con i cluster Google Kubernetes Engine (GKE).

Panoramica

kubectl è uno strumento a riga di comando che puoi utilizzare per interagire con i cluster GKE. Per utilizzare kubectl con GKE, devi installare lo strumento e configurarlo in modo che comunichi con i tuoi cluster. Se esegui più cluster in Google Cloud, è necessaria un'ulteriore configurazione di kubectl.

In questa pagina vengono visualizzate le seguenti informazioni:

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

  • Abilita l'API Google Kubernetes Engine.
    • Abilita l'API Google Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installa e initialize gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.

Installazione di kubectl

Puoi installare kubectl utilizzando Google Cloud CLI o un gestore di pacchetti esterno, come apt o yum.

gcloud

  1. Installa il componente kubectl:

    gcloud components install kubectl

  2. Verifica che kubectl sia installato controllando che sia installata la versione più recente:

    kubectl version --client

apt

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

  2. Se il repository cloud-sdk non è presente nell'elenco, installa gcloud CLI.

  3. Installa il componente kubectl:

    apt-get update
apt-get install -y kubectl

  4. Verifica che kubectl sia installato controllando che sia installata la versione più recente:

    kubectl version --client

slurp

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

  2. Installa il componente kubectl:

    yum install -y kubectl

  3. Verifica che kubectl sia installato controllando che sia installata la versione più recente:

    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 framework plug-in di credenziali Client-go per fornire token di autenticazione per comunicare con i cluster GKE.

Prima del rilascio della versione 1.26 di Kubernetes, gcloud CLI inizierà a richiedere l'installazione del programma binario gke-gcloud-auth-plugin. Se non sono installati, le installazioni esistenti di kubectl o di altri client Kubernetes personalizzati smetteranno di funzionare.

Devi installare 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:

  1. Controlla la versione binaria di gke-gcloud-auth-plugin:

    gke-gcloud-auth-plugin --version

  2. Aggiorna la configurazione di 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: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.

  3. 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 è necessario questo plug-in, consulta la KEP di Kubernetes.

Interagisci con kubectl

Kubernetes utilizza un file YAML chiamato kubeconfig per archiviare le informazioni di autenticazione del cluster per kubectl. Per impostazione predefinita, il file viene salvato in $HOME/.kube/config.

kubeconfig contiene un gruppo di parametri di accesso chiamati contesti. Ogni contesto contiene un cluster Kubernetes, un utente e uno spazio dei nomi predefinito facoltativo. kubectl si riferisce ai contesti durante l'esecuzione dei 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 corrente nel file kubeconfig.
  • Esegui i comandi kubectl su un cluster specifico utilizzando il flag --cluster.

Visualizza kubeconfig

Per visualizzare il valore kubeconfig del tuo ambiente, esegui questo comando:

kubectl config view

Il comando restituisce un elenco di tutti i cluster per cui sono state generate le voci kubeconfig. Se è presente un cluster GKE, puoi eseguire i comandi kubectl sul cluster nel tuo ambiente attuale. In caso contrario, devi archiviare le informazioni sul cluster kubectl.

Visualizza il contesto attuale per kubectl

Il contesto attuale è il cluster attualmente predefinito per kubectl. Tutti i comandi kubectl vengono eseguiti sul cluster.

Quando crei un cluster utilizzando gcloud container clusters create-auto, viene aggiunta automaticamente una voce al file kubeconfig nel tuo ambiente e il contesto attuale cambia 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 dal suo computer, il suo kubeconfig viene aggiornato, ma il tuo non lo è. La voce kubeconfig contiene:

Per generare un contesto kubeconfig nel tuo ambiente, assicurati di disporre dell'autorizzazione container.clusters.get. Il ruolo IAM con privilegi limitati che fornisce questa autorizzazione è container.clusterViewer.

Per generare un contesto kubeconfig per un cluster specifico, esegui questo comando:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=CLUSTER_REGION

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del tuo cluster.
  • COMPUTE_REGION: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --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 il server API Kubernetes utilizzato da kubectl e da altri servizi per comunicare con il piano di controllo del cluster.

I cluster privati hanno due indirizzi IP di 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 all'endpoint non sia disabilitato, nel qual caso verrà utilizzato l'indirizzo IP privato.

Per i cluster privati, se preferisci utilizzare l'indirizzo IP interno come endpoint, esegui questo comando:

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Sostituisci CLUSTER_NAME con il nome del 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 cambiare il contesto attuale di kubectl in quel 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: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --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 tutti i comandi kubectl su 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.

Ad esempio, considera 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 il contesto attuale. Per eseguire il deployment dell'applicazione in my-new-cluster senza modificare il contesto corrente, esegui 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 la sezione Risoluzione dei problemi più comuni.

Ambiti di autenticazione insufficienti

Quando esegui gcloud container clusters get-credentials ricevi il seguente 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 istruzioni su come modificare gli 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 che interagiscono con GKE, installa gke-gcloud-auth-plugin come descritto nelle 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: panico: nessun provider di autenticazione trovato per il nome gcp

L'errore no Auth Provider found for name "gcp" viene ricevuto se i client Kubernetes kubectl o personalizzati 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:

  1. Installa gke-gcloud-auth-plugin come descritto nelle Istruzioni di installazione.

  2. Esegui l'aggiornamento alla versione più recente di gcloud CLI utilizzando gcloud components update.

  3. 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: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.

AVVISO: il plug-in gcp auth è deprecato. Utilizza gcloud

Potresti visualizzare questo messaggio di avviso dopo aver installato gke-gcloud-auth-plugin ed eseguito un comando kubectl su un cluster GKE. Questo messaggio viene visualizzato se la versione del client è precedente alla 1.26.

Per indicare al tuo client di utilizzare invece il plug-in di autenticazione gke-gcloud-auth-plugin:

  1. Apri lo script di accesso alla shell in un editor di testo:

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Se utilizzi PowerShell, ignora questo passaggio.

  2. 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')

  3. Applica la variabile nel tuo ambiente:

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    Esci dal terminale e apri una nuova sessione del terminale.

  4. Aggiorna l'interfaccia alla gcloud CLI:

    gcloud components update

  5. Esegui l'autenticazione sul cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • COMPUTE_REGION: la regione di Compute Engine per il cluster. Per i cluster a livello di zona, utilizza --zone=COMPUTE_ZONE.

Passaggi successivi

Provalo

Se non hai mai utilizzato Google Cloud, crea un account per valutare le prestazioni di GKE in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Prova GKE gratuitamente