Fehlerbehebung für das kubectl-Befehlszeilentool

Auf dieser Seite erfahren Sie, wie Sie Probleme mit dem kubectl-Befehlszeilentool beheben, wenn Sie in der Google Kubernetes Engine (GKE) arbeiten. Allgemeinere Tipps finden Sie in der Kubernetes-Dokumentation unter Fehlerbehebung bei kubectl.

Fehler bei der Authentifizierung und Autorisierung

Wenn bei der Verwendung der Befehle des kubectl-Befehlszeilentools Fehler im Zusammenhang mit Authentifizierung und Autorisierung auftreten, finden Sie in den folgenden Abschnitten entsprechende Informationen.

Fehler: 401 (Unauthorized)

Wenn Sie eine Verbindung zu GKE-Clustern herstellen, kann ein Authentifizierungs- und Autorisierungsfehler mit dem HTTP-Statuscode 401 (Unauthorized) auftreten. Dieses Problem kann auftreten, wenn Sie versuchen, einen kubectl-Befehl in Ihrem GKE-Cluster aus einer lokalen Umgebung auszuführen. Weitere Informationen finden Sie unter Problem: Authentifizierungs- und Autorisierungsfehler.

Fehler: Unzureichende Authentifizierungsbereiche

Wenn Sie gcloud container clusters get-credentials ausführen, wird möglicherweise 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 cloud-platform-Bereich hat, auf die Kubernetes Engine API zugreifen.

Um diesen Fehler zu beheben, gewähren Sie den fehlenden cloud-platform-Bereich. Eine Anleitung zum Ändern der Bereiche auf Ihrer Compute Engine-VM-Instanz finden Sie in der Compute Engine-Dokumentation unter Dienstkonten für Instanzen erstellen und aktivieren.

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

Beim Ausführen von kubectl-Befehlen oder benutzerdefinierten Clients, die mit GKE interagieren, können ähnliche Fehlermeldungen wie die folgenden auftreten:

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.

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

Installieren Sie gke-gcloud-auth-plugin wie unter Erforderliche Plug-ins installieren beschrieben, um das Problem zu beheben.

Fehler: Kein Authentifizierungsanbieter gefunden

Der folgende Fehler tritt auf, wenn kubectl oder benutzerdefinierte Kubernetes-Clients mit Kubernetes client-go 1.26 oder höher erstellt wurden:

no Auth Provider found for name "gcp"

So beheben Sie das Problem:

  1. Installieren Sie gke-gcloud-auth-plugin wie unter Erforderliche Plug-ins installieren beschrieben.

  2. Aktualisieren Sie auf die neueste Version der gcloud CLI:

    gcloud components update

  3. Aktualisieren Sie die Datei kubeconfig:

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

    Ersetzen Sie Folgendes:

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

Fehler: 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:

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

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

    Ersetzen Sie Folgendes:

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

Problem: Befehl kubectl wurde nicht gefunden

Wenn Sie die Meldung erhalten, dass der Befehl kubectl nicht gefunden wurde, installieren Sie die kubectl-Binärdatei neu und legen Sie die Umgebungsvariable $PATH fest:

  1. Installieren Sie die kubectl-Binärdatei:

    gcloud components update kubectl

  2. Wenn Sie vom Installationsprogramm aufgefordert werden, die Umgebungsvariable $PATH zu ändern, geben Sie y ein, um fortzufahren. Durch die Änderung dieser Variable können Sie kubectl-Befehle verwenden, ohne den vollständigen Pfad eingeben zu müssen.

    Alternativ können Sie die folgende Zeile an den Speicherort für Umgebungsvariablen in der verwendeten Shell einfügen, z. B. ~/.bashrc (oder ~/.bash_profile unter macOS):

    export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

  3. Führen Sie den folgenden Befehl aus, um die aktualisierte Datei zu laden. Im folgenden Beispiel wird .bashrc verwendet:

    source ~/.bashrc

    Wenn Sie macOS verwenden, verwenden Sie ~/.bash_profile anstelle von .bashrc.

Problem: kubectl-Befehle geben den Fehler "Verbindung verweigert" aus

Wenn kubectl-Befehle den Fehler „Verbindung verweigert“ zurückgeben, müssen Sie den Clusterkontext mit dem folgenden Befehl festlegen:

gcloud container clusters get-credentials CLUSTER_NAME

Ersetzen Sie CLUSTER_NAME durch den Namen Ihres Clusters. Wenn Sie sich nicht sicher sind, was Sie für den Clusternamen eingeben sollen, verwenden Sie den folgenden Befehl, um die verfügbaren Cluster aufzulisten:

gcloud container clusters list

Fehler: Zeitüberschreitung beim kubectl-Befehl

Wenn Sie einen Cluster erstellt und versucht haben, einen kubectl-Befehl für den Cluster auszuführen, aber der kubectl-Befehl ein Zeitlimit überschreitet, wird eine Fehlermeldung ähnlich der folgenden angezeigt:

  • Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
  • Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout.

Diese Fehler weisen darauf hin, dass kubectl nicht mit der Clustersteuerungsebene kommunizieren kann.

Prüfen und legen Sie den Kontext fest, in dem der Cluster festgelegt ist, und sorgen Sie für eine Verbindung zum Cluster:

  1. Rufen Sie $HOME/.kube/config auf oder führen Sie den Befehl kubectl config view aus, um zu prüfen, ob die Konfigurationsdatei den Clusterkontext und die externe IP-Adresse der Steuerungsebene enthält.

  2. Legen Sie die Clusteranmeldedaten fest:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: Der Name Ihres Clusters.
    • COMPUTE_LOCATION: der Compute Engine-Standort.
    • PROJECT_ID: die ID des Projekts, in dem der Cluster erstellt wurde.

  3. Wenn es sich bei dem Cluster um einen privaten GKE-Cluster handelt, muss die Liste der vorhandenen autorisierten Netzwerke die ausgehende IP-Adresse des Computers enthalten, von dem aus Sie eine Verbindung herstellen möchten. Sie finden Ihre autorisierten Netzwerke in der Console oder durch Ausführen des folgenden Befehls:

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(masterAuthorizedNetworksConfig.cidrBlocks[])"

    Wenn die ausgehende IP-Adresse des Computers nicht in der Liste der autorisierten Netzwerke in der Ausgabe des vorherigen Befehls enthalten ist, führen Sie einen der folgenden Schritte aus:

    • Wenn Sie die Console verwenden, erhöhen Sie die Wahrscheinlichkeit, dass Ihre Cluster-Steuerungsebene erreichbar ist. Implementieren Sie dazu eine der Konfigurationen für den Zugang zu den Clusterendpunkten. Weitere Informationen finden Sie unter Zugriff auf Clusterendpunkte.
    • Wenn Sie eine Verbindung über Cloud Shell herstellen, folgen Sie der Anleitung unter Mit Cloud Shell auf einen privaten Cluster zugreifen.

Fehler: kubectl-Befehle geben den Fehler „Es konnte keine API-Version festgelegt werden“ zurück

Wenn kubectl-Befehle den Fehler failed to negotiate an API version zurückgeben, müssen Sie dafür sorgen, dass kubectl Anmeldedaten für die Authentifizierung hat:

gcloud auth application-default login

Problem: Die Befehle kubectl logs, attach, exec oder port-forward reagieren nicht mehr

Wenn die Befehle kubectl, logs, attach, exec oder port-forward nicht mehr reagieren, kann der API-Server in der Regel nicht mit den Knoten kommunizieren.

Prüfen Sie zuerst, ob Ihr Cluster Knoten hat. Wenn Sie die Anzahl der Knoten in Ihrem Cluster bis auf null reduziert haben, funktionieren Befehle nicht. Passen Sie die Größe Ihres Clusters an, um das Problem zu beheben. Es muss mindestens ein Knoten vorhanden sein.

Wenn Ihr Cluster mindestens einen Knoten hat, prüfen Sie, ob Sie SSH- oder Konnectivity-Proxy-Tunnel für eine sichere Kommunikation verwenden. In den folgenden Abschnitten werden die Schritte zur Fehlerbehebung für die einzelnen Dienste beschrieben:

SSH-Probleme beheben

Wenn Sie SSH verwenden, speichert GKE eine Datei mit dem öffentlichen SSH-Schlüssel in den Metadaten Ihres Compute Engine-Projekts. Alle Compute Engine-VMs, die von Google bereitgestellte Images verwenden, prüfen regelmäßig die allgemeinen Metadaten ihres Projekts und die Instanzmetadaten auf SSH-Schlüssel, um diese der Liste mit autorisierten Nutzern der VM hinzuzufügen. GKE fügt dem Compute Engine-Netzwerk außerdem eine Firewallregel hinzu, mit der der SSH-Zugriff von der IP-Adresse der Steuerungsebene auf jeden Knoten im Cluster möglich ist.

Die folgenden Einstellungen können zu Problemen mit der SSH-Kommunikation führen:

  • Die Firewallregeln Ihres Netzwerks lassen keinen SSH-Zugriff auf die Steuerungsebene zu.

    Alle Compute Engine-Netzwerke werden mit einer Firewallregel mit dem Namen default-allow-ssh erstellt, die den SSH-Zugriff über alle IP-Adressen ermöglicht (erfordert einen gültigen privaten Schlüssel). Von GKE wird darüber hinaus für jeden öffentlichen Cluster eine SSH-Regel der Form gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh eingefügt, mit der der SSH-Zugriff speziell von der Steuerungsebene des Clusters auf dessen Knoten möglich ist.

    Wenn keine dieser Regeln existiert, kann die Steuerungsebene keine SSH-Tunnel öffnen.

    Prüfen Sie, ob diese Regeln in Ihrer Konfiguration vorhanden sind, um festzustellen, ob dies die Ursache des Problems ist.

    Um dieses Problem zu beheben, identifizieren Sie das Tag, das sich auf allen Clusterknoten befindet, und fügen Sie dann noch einmal eine Firewallregel hinzu, die den Zugriff auf VMs mit diesem Tag von der IP-Adresse der Steuerungsebene ermöglicht.

  • Der Metadaten-Eintrag Ihres Projekts für ssh-keys ist voll.

    Wenn der Metadateneintrag ssh-keys des Projekts nahe der maximalen Größe liegt, kann GKE keinen eigenen SSH-Schlüssel hinzufügen, um SSH-Tunnel zu öffnen.

    Prüfen Sie, ob das Problem hier liegt, indem Sie die Länge der Liste von ssh-keys prüfen. Sie können die Metadaten Ihres Projekts mit dem folgenden Befehl aufrufen. Optional können Sie das Flag --project angeben:

    gcloud compute project-info describe [--project=PROJECT_ID]

    Löschen Sie zum Beheben dieses Problems einige SSH-Schlüssel, die nicht mehr benötigt werden.

  • Sie haben auf den VMs im Cluster für ein Metadatenfeld den Schlüssel ssh-keys festgelegt.

    Der Knoten-Agent auf VMs bevorzugt pro Instanz zugewiesene SSH-Schlüssel gegenüber projektweiten SSH-Schlüsseln. Wenn Sie also speziell auf den Clusterknoten SSH-Schlüssel eingerichtet haben, dann wird der SSH-Schlüssel der Steuerungsebene in den Projektmetadaten von den Knoten nicht beachtet.

    Führen Sie zum Prüfen gcloud compute instances describe VM_NAME aus und suchen Sie in den Metadaten nach dem Feld ssh-keys.

    Löschen Sie zum Beheben des Problems die pro Instanz zugewiesenen SSH-Schlüssel aus den Instanzmetadaten.

Probleme mit dem Konnectivity-Proxy beheben

Sie können prüfen, ob Ihr Cluster den Konnectivity-Proxy verwendet, indem Sie nach der folgenden Systembereitstellung suchen:

kubectl get deployments konnectivity-agent --namespace kube-system

Die folgenden Einstellungen können zu Problemen mit dem Konnectivity-Proxy führen:

  • Die Firewallregeln Ihres Netzwerks lassen keinen Zugriff des Konnectivity-Agents auf die Steuerungsebene zu.

    Bei der Clustererstellung stellen Konnectivity-Agent-Pods eine Verbindung zur Steuerungsebene über Port 8132 her und halten sie aufrecht. Wenn einer der kubectl-Befehle ausgeführt wird, verwendet der API-Server diese Verbindung, um mit dem Cluster zu kommunizieren.

    Wenn die Firewallregeln Ihres Netzwerks Regeln zum Ablehnen von ausgehendem Traffic enthalten, kann dies verhindern, dass der Agent eine Verbindung herstellt.

    Prüfen Sie, ob das Problem dadurch verursacht wird, indem Sie die Firewallregeln Ihres Netzwerks auf Regeln für den ausgehenden Traffic prüfen.

    Um dieses Problem zu beheben, erlauben Sie ausgehenden Traffic an die Clustersteuerungsebene auf Port 8132. (Zum Vergleich: Der API-Server verwendet 443).

  • Die Netzwerkrichtlinie Ihres Clusters blockiert eingehenden Traffic vom Namespace kube-system zum Namespace workload.

    Diese Funktionen sind für ein korrektes Funktionieren des Clusters nicht erforderlich. Wenn Sie es vorziehen, Ihr Clusternetzwerk für alle externen Zugriffe zu sperren, können Sie Funktionen wie diese nicht mehr verwenden.

    Führen Sie den folgenden Befehl aus, um die Netzwerkrichtlinien im betroffenen Namespace zu suchen, um zu prüfen, ob dies die Ursache des Problems ist:

    kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

    Fügen Sie dem Feld spec.ingress der Netzwerkrichtlinien Folgendes hinzu, um das Problem zu beheben:

    - from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

Nächste Schritte

Wenn Sie weitere Unterstützung benötigen, wenden Sie sich an den Cloud Customer Care.