kubectl installieren und Clusterzugriff konfigurieren

Autopilot Standard

---

Auf dieser Seite wird beschrieben, wie Sie das kubectl-Befehlszeilentool installieren und konfigurieren, um mit Ihren GKE-Clustern (Google Kubernetes Engine) zu interagieren.

Überblick

kubectl ist ein Befehlszeilentool, mit dem Sie mit Ihren GKE-Clustern interagieren können. Wenn Sie kubectl mit GKE verwenden möchten, müssen Sie das Tool installieren und für die Kommunikation mit Ihren Clustern konfigurieren. Wenn Sie mehrere Cluster in Google Cloud ausführen, ist eine weitere kubectl-Konfiguration erforderlich.

Auf dieser Seite wird Folgendes beschrieben:

• Funktionsweise von kubectl.
• Installation von kubectl und erforderlichen Abhängigkeiten, sofern vorhanden.
• Festlegen des Standardclusters für kubectl
• Ausführen von kubectl-Befehlen für einen bestimmten Cluster

Vorbereitung

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

• Aktivieren Sie die Google Kubernetes Engine API.
Google Kubernetes Engine API aktivieren
• Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit gcloud components update ab.
  Hinweis: Legen Sie für vorhandene Installationen der gcloud CLI die compute/region- und compute/zone-Attribute fest. Durch das Festlegen von Standardspeicherorten können Sie in der gcloud CLI Fehler wie One of [--zone, --region] must be supplied: Please specify location vermeiden.

kubectl installieren

Sie können kubectl mithilfe der Google Cloud CLI oder eines externen Paketmanagers wie apt oder yum installieren.

gcloud

1. Installieren Sie die Komponente kubectl:

   gcloud components install kubectl
   

2. Prüfen Sie, ob kubectl installiert ist. Prüfen Sie dazu, ob die neueste Version vorhanden ist:

   kubectl version --client
   

apt

1. Prüfen Sie, ob das Repository cloud-sdk vorhanden ist:

   grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
   

   Die Ausgabe sieht in etwa so aus:

   deb  [signed-by=/usr/share/keyrings/cloud.google.gpg]  https://packages.cloud.google.com/apt cloud-sdk main
   

2. Wenn das Repository cloud-sdk nicht aufgeführt ist, installieren Sie die gcloud CLI.

3. Installieren Sie die Komponente kubectl:

   apt-get update
   apt-get install -y kubectl
   

4. Prüfen Sie, ob kubectl installiert ist. Prüfen Sie dazu, ob die neueste Version vorhanden ist:

   kubectl version --client
   

yum

1. Prüfen Sie, ob das Repository cloud-sdk vorhanden ist:

   yum repolist | grep "google-cloud-sdk"
   

   Die Ausgabe sieht etwa so aus:

   google-cloud-sdk    Google Cloud SDK    2,205
   

2. Installieren Sie die Komponente kubectl:

   yum install -y kubectl
   

3. Prüfen Sie, ob kubectl installiert ist. Prüfen Sie dazu, ob die neueste Version vorhanden ist:

   kubectl version --client
   

Erforderliche Plug-ins installieren

kubectl und andere Kubernetes-Clients benötigen das Authentifizierungs-Plug-in gke-gcloud-auth-plugin, das das Framework Client-go-Anmeldedaten-Plug-ins verwendet, um Authentifizierungstokens für die Kommunikation mit GKE-Clustern bereitzustellen.

Vor der Veröffentlichung von Kubernetes Version 1.26 erfordert die gcloud CLI die Installation der Binärdatei gke-gcloud-auth-plugin. Wenn nicht installiert, funktionieren vorhandene Installationen von kubectl oder anderen benutzerdefinierten Kubernetes-Clients nicht mehr.

Sie müssen dieses Plug-in installieren, um kubectl und andere Clients für die Interaktion mit GKE verwenden zu können. Vorhandene Clients zeigen eine Fehlermeldung an, wenn das Plug-in nicht installiert ist.

Bevor Sie beginnen, prüfen Sie, ob das Plug-in bereits installiert ist:

gke-gcloud-auth-plugin --version

Wenn in der Ausgabe Versionsinformationen angezeigt werden, überspringen Sie diesen Abschnitt.

Sie können das Authentifizierungs-Plug-in mit der gcloud CLI oder einem externen Paketmanager wie apt oder yum installieren.

gcloud

Installieren Sie die gke-gcloud-auth-plugin-Binärdatei:

  gcloud components install gke-gcloud-auth-plugin

apt

Installieren Sie die gke-gcloud-auth-plugin-Binärdatei:

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

yum

Installieren Sie die gke-gcloud-auth-plugin-Binärdatei:

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

Prüfen Sie die Installation der Binärdatei gke-gcloud-auth-plugin:

1. Prüfen Sie die Version der Binärdatei gke-gcloud-auth-plugin:

   gke-gcloud-auth-plugin --version
   

2. Aktualisieren Sie die kubectl-Konfiguration, um das Plug-in zu verwenden:

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

   Dabei gilt:

   • CLUSTER_NAME: Der Name Ihres Clusters.
   • COMPUTE_REGION: die Compute Engine-Region für den Cluster. Verwenden Sie für zonale Cluster --zone=COMPUTE_ZONE.

3. Konfiguration prüfen:

   kubectl get namespaces
   

   Die entsprechende Ausgabe sieht etwa so aus:

   NAME              STATUS   AGE
   default           Active   51d
   kube-node-lease   Active   51d
   kube-public       Active   51d
   kube-system       Active   51d
   

Weitere Informationen dazu, warum dieses Plug-in erforderlich ist, finden Sie unter Kubernetes KEP.

Mit kubectl interagieren

Kubernetes verwendet eine YAML-Datei namens kubeconfig, um Informationen zur Clusterauthentifizierung für kubectl zu speichern. Standardmäßig wird die Datei unter $HOME/.kube/config gespeichert.

kubeconfig enthält eine Gruppe von Zugriffsparametern, die als Kontexte bezeichnet werden. Jeder Kontext enthält einen Kubernetes-Cluster, einen Nutzer und einen optionalen Standard-Namespace. kubectl bezieht sich beim Ausführen von Befehlen auf Kontexte.

Mit den folgenden Aufgaben können Sie kubectl konfigurieren:

• Wählen Sie aus, mit welchem Cluster kubectl kommuniziert.
• Legen Sie einen Standardcluster für kubectl fest, indem Sie den aktuellen Kontext in der Datei kubeconfig festlegen.
• Mit dem Flag --cluster können Sie kubectl-Befehle für einen bestimmten Cluster ausführen.

kubeconfig aufrufen

Führen Sie den folgenden Befehl aus, um die kubeconfig der Umgebung aufzurufen:

kubectl config view

Der Befehl gibt eine Liste aller Cluster zurück, für die Einträge in kubeconfig generiert wurden. Wenn ein GKE-Cluster aufgeführt ist, können Sie kubectl-Befehle für diesen Cluster in Ihrer aktuellen Umgebung ausführen. Andernfalls müssen Sie Clusterinformationen für kubectl speichern.

Aktuellen Kontext für kubectl ansehen

Der aktuelle Kontext ist der Cluster, der derzeit als Standard für kubectl gilt. Alle kubectl-Befehle werden über diesen Cluster ausgeführt.

Wenn Sie einen Cluster mit gcloud container clusters create-auto erstellen, wird der kubeconfig-Datei in Ihrer Umgebung automatisch ein Eintrag hinzugefügt und der aktuelle Kontext wird auf diesen Cluster umgestellt. Beispiel:

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

Führen Sie den folgenden Befehl aus, um den aktuellen Kontext für kubectl aufzurufen:

kubectl config current-context

Clusterinformationen für kubectl speichern

Wenn Sie einen Cluster über die Google Cloud Console oder die gcloud CLI auf einem anderen Computer erstellen, wird die Datei kubeconfig Ihrer Umgebung nicht aktualisiert. Ähnlich verhält es sich, wenn ein Mitglied des Projektteams mit der gcloud CLI einen Cluster auf seinem eigenen Computer erstellt. Dann wird die kubeconfig des Mitglieds aktualisiert, nicht Ihre. Der Eintrag in kubeconfig enthält entweder:

• Ihre Anmeldedaten, wie in gcloud auth list gezeigt, oder
• Die Standardanmeldedaten für Anwendungen, falls konfiguriert.

Zum Generieren eines kubeconfig-Kontexts in Ihrer Umgebung benötigen Sie die Berechtigung container.clusters.get. Die IAM-Rolle mit den geringsten Berechtigungen, die diese Berechtigung bietet, ist container.clusterViewer.

Führen Sie den folgenden Befehl aus, um einen kubeconfig-Kontext für einen bestimmten Cluster zu generieren:

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

Dabei gilt:

• CLUSTER_NAME: Der Name Ihres Clusters.
• COMPUTE_REGION: die Compute Engine-Region für den Cluster. Verwenden Sie für zonale Cluster --zone=COMPUTE_ZONE.

Hinweis: Mit der Ausführung von gcloud container clusters get-credentials wird auch der aktuelle Kontext für kubectl auf diesen Cluster umgestellt.

kubeconfig-Eintrag mithilfe der internen IP-Adresse eines privaten Clusters generieren

Alle Cluster haben einen kanonischen Endpunkt. Der Endpunkt stellt den Kubernetes API-Server zur Verfügung, den kubectl und andere Dienste zur Kommunikation mit der Cluster-Steuerungsebene nutzen.

Private Cluster haben zwei separate Endpunkt-IP-Adressen: privateEndpoint (eine interne IP-Adresse) und publicEndpoint (eine externe IP-Adresse). Das Feld endpoint bezieht sich auf die externe IP-Adresse, sofern der öffentliche Zugriff auf den Endpunkt nicht deaktiviert ist. In diesem Fall wird die private IP-Adresse verwendet.

Wenn Sie bei privaten Clustern die interne IP-Adresse als Endpunkt verwenden möchten, führen Sie folgenden Befehl aus:

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

Ersetzen Sie CLUSTER_NAME durch den Namen Ihres Clusters.

Bei der Ausführung von get-credentials wird standardmäßig die im Feld endpoint angegebene IP-Adresse verwendet.

Standardcluster für kubectl-Befehle festlegen

Wenn Sie bereits einen kubeconfig-Eintrag für einen Cluster generiert haben, können Sie den aktuellen Kontext für kubectl auf diesen Cluster umstellen. Dazu führen Sie den folgenden Befehl aus:

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

Dabei gilt:

• CLUSTER_NAME: Der Name Ihres Clusters.
• COMPUTE_REGION: die Compute Engine-Region für den Cluster. Verwenden Sie für zonale Cluster --zone=COMPUTE_ZONE.

Angenommen Sie haben ein Projekt mit den beiden Clustern my-cluster und my-new-cluster. Der aktuelle Kontext lautet my-new-cluster, Sie möchten aber alle kubectl-Befehle für my-cluster ausführen. Führen Sie den folgenden Befehl aus, um den aktuellen Kontext von my-new-cluster in my-cluster zu ändern:

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

Einzelne kubectl-Befehle für einen bestimmten Cluster ausführen

Mit --cluster=CLUSTER_NAME können Sie einzelne kubectl-Befehle für einen bestimmten Cluster ausführen.

Angenommen Sie haben eine Umgebung mit den beiden Clustern my-cluster und my-new-cluster, in der der aktuelle Kontext my-cluster ist. Sie möchten eine Anwendung in my-new-cluster bereitstellen, den aktuellen Kontext aber nicht ändern. Mit diesem Befehl stellen Sie die Anwendung in my-new-cluster bereit, ohne den aktuellen Kontext zu ändern:

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in der Fehlerbehebung für gängige Probleme.

Unzureichende Authentifizierungsbereiche

Wenn Sie gcloud container clusters get-credentials ausführen, wird der folgende Fehler angezeigt:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Dieser Fehler tritt auf, weil Sie von einer Compute Engine-VM, die nicht den Bereich cloud-platform hat, auf die Kubernetes Engine API zugreifen. Eine Anleitung zum Ändern der Bereiche auf Ihrer Compute Engine-VM-Instanz finden Sie unter Dienstkonten für Instanzen erstellen und aktivieren.

FEHLER: Ausführbare Datei gke-gcloud-auth-plugin nicht gefunden

Wenn beim Versuch, kubectl oder benutzerdefinierte Clients auszuführen, die mit GKE interagieren, die folgende Fehlermeldung angezeigt wird, installieren Sie das gke-gcloud-auth-plugin wie in den Installationsanweisungen beschrieben. Die Fehlermeldungen sehen etwa so aus:

• Fehlerbeispiel

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.

• Fehlerbeispiel

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

FEHLER: Panik: Kein Auth-Anbieter für Name GCP gefunden

Der Fehler no Auth Provider found for name "gcp" wird ausgegeben, wenn kubectl oder benutzerdefinierte Kubernetes-Clients mit Kubernetes client-go 1.26 oder höher erstellt wurden, wie unter Funktionsweise beschrieben. Dieser Fehler kann so behoben werden:

1. Installieren Sie gke-gcloud-auth-plugin wie in der Installationsanleitung beschrieben.

2. Aktualisieren Sie mit gcloud components update die neueste Version der gcloud CLI.

3. Aktualisieren Sie die Datei kubeconfig.

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

   Dabei gilt:

   • CLUSTER_NAME: Der Name Ihres Clusters.
   • COMPUTE_REGION: die Compute Engine-Region für den Cluster. Verwenden Sie für zonale Cluster --zone=COMPUTE_ZONE.

WARNUNG: Das GCP-Authentifizierungs-Plug-in wurde verworfen, verwenden Sie stattdessen gcloud

Diese Warnmeldung wird möglicherweise angezeigt, nachdem Sie gke-gcloud-auth-plugin installiert und einen kubectl-Befehl für einen GKE-Cluster ausgeführt haben. Diese Meldung wird angezeigt, wenn Ihre Clientversion älter als 1.26 ist.

Damit Ihr Client stattdessen das Authentifizierungs-Plug-in gke-gcloud-auth-plugin verwendet, gehen Sie so vor:

1. Öffnen Sie das Shell-Anmeldeskript in einem Texteditor:

   Bash

   vi ~/.bashrc
   

   Zsh

   vi ~/.zshrc
   

   Wenn Sie PowerShell verwenden, überspringen Sie diesen Schritt.

2. Legen Sie die folgende Umgebungsvariable fest:

   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. Wenden Sie die Variable in Ihrer Umgebung an:

   Bash

   source ~/.bashrc
   

   Zsh

   source ~/.zshrc
   

   PowerShell

   Beenden Sie das Terminal und öffnen Sie eine neue Terminalsitzung.

4. gcloud CLI aktualisieren

   gcloud components update
   

5. Beim Cluster authentifizieren:

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

   Dabei gilt:

   • CLUSTER_NAME: Der Name Ihres Clusters.
   • COMPUTE_REGION: die Compute Engine-Region für den Cluster. Verwenden Sie für zonale Cluster --zone=COMPUTE_ZONE.

Nächste Schritte

• Zugriff auf Ressourcen in GKE-Clustern autorisieren
• Authentifizierung bei Google Cloud-Diensten aus GKE-Arbeitslasten
• Spickzettel zu kubectl lesen

Jetzt testen

Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit von GKE in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

GKE kostenlos testen