Clusterzugriff für "kubectl" konfigurieren

Auf dieser Seite wird erläutert, wie Sie den Clusterzugriff für das kubectl-Befehlszeilentool in Google Kubernetes Engine (GKE) konfigurieren.

Übersicht

Wenn Sie innerhalb Ihres Google Cloud-Projekts mehrere Cluster ausführen, müssen Sie festlegen, mit welchem Cluster kubectl kommuniziert. Sie können einen Standardcluster für kubectl festlegen, wenn Sie den aktuellen Kontext in der Kubernetes-Datei kubeconfig festlegen. Außerdem können Sie mit dem Flag --cluster kubectl-Befehle für einen bestimmten Cluster ausführen.

In den folgenden Abschnitten wird erläutert, wie kubeconfig funktioniert, wie ein Standardcluster für kubectl festgelegt wird und wie einzelne kubectl-Befehle für einen bestimmten Cluster ausgeführt werden.

Vorbereitung

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

Mit den folgenden Methoden können Sie die gcloud-Einstellungen festlegen:

  • Verwenden Sie gcloud init, wenn Sie die Standardeinstellungen ansehen möchten.
  • Verwenden Sie gcloud config, um Ihre Projekt-ID, Zone und Region individuell festzulegen.

gcloud init verwenden

Wenn Sie die Fehlermeldung One of [--zone, --region] must be supplied: Please specify location erhalten, führen Sie diesen Abschnitt aus.

  1. Führen Sie gcloud init aus und folgen Sie der Anleitung:

    gcloud init

    Wenn Sie SSH auf einem Remote-Server verwenden, können Sie mit dem Flag --console-only verhindern, dass mit dem Befehl ein Browserfenster geöffnet wird:

    gcloud init --console-only
  2. Folgen Sie der Anleitung, um gcloud zur Verwendung Ihres Google Cloud-Kontos zu autorisieren.
  3. Erstellen Sie eine neue Konfiguration oder wählen Sie eine vorhandene aus.
  4. Wählen Sie ein Google Cloud-Projekt aus.
  5. Wählen Sie eine Compute Engine-Standardzone für zonale Cluster oder eine Region für regionale oder Autopilot-Cluster aus.

gcloud config verwenden

  • Legen Sie Ihre standardmäßige Projekt-ID fest: 
    gcloud config set project PROJECT_ID
  • Wenn Sie mit zonalen Clustern arbeiten, legen Sie die Standardzone für Compute Engine fest: 
    gcloud config set compute/zone COMPUTE_ZONE
  • Wenn Sie mit Autopilot oder regionalen Clustern arbeiten, legen Sie die Compute-Standardregion fest: 
    gcloud config set compute/region COMPUTE_REGION
  • Aktualisieren Sie gcloud auf die neueste Version:
    gcloud components update

Kubernetes-Konfigurationsdatei

Kubernetes verwendet eine YAML-Datei namens kubeconfig, um Informationen zur Clusterauthentifizierung für kubectl zu speichern. kubeconfig enthält eine Liste von Kontexten, auf die kubectl beim Ausführen von Befehlen verweist. Standardmäßig wird die Datei unter $HOME/.kube/config gespeichert.

Ein Kontext ist eine Gruppe von Zugriffsparametern. Jeder Kontext enthält einen Kubernetes-Cluster, einen Nutzer und einen Namespace. 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 erstellen, wird der kubeconfig in Ihrer Umgebung automatisch ein Eintrag hinzugefügt und der aktuelle Kontext wird auf diesen Cluster umgestellt:

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

Wenn Sie einen Cluster über die Google Cloud Console oder mit dem gcloud-Tool über einen anderen Computer erstellen, wird die kubeconfig Ihrer Umgebung nicht aktualisiert. Ähnlich verhält es sich, wenn ein Mitglied des Projektteams mit gcloud einen Cluster auf seinem eigenen Computer erstellt. Dann wird die kubeconfig des Mitglieds aktualisiert, nicht Ihre. Folgen Sie der Anleitung unter kubeconfig-Eintrag generieren, um diese Cluster zu Ihrer lokalen kubeconfig hinzuzufügen.

Clusterendpunkt

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. Die Endpunkt-IP-Adresse wird in der Cloud Console im Feld Endpunkte auf dem Tab „Details” des Clusters und in der Ausgabe von gcloud container clusters describe im Feld endpoint angezeigt.

Wenn Sie gcloud container clusters get-credentials ausführen, sehen Sie, dass der Befehl den Clusterendpunkt als Teil der Aktualisierung von kubeconfig abruft.

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, es sei denn, der öffentliche Zugriff auf den Endpunkt ist deaktiviert. In diesem Fall wird die private IP-Adresse verwendet.

Bei der Ausführung von get-credentials wird standardmäßig die im Feld endpoint angegebene IP verwendet. Wenn Sie für private Cluster die interne IP-Adresse als Endpunkt verwenden möchten, lesen Sie die Informationen unter Eintrag in kubeconfig mithilfe der internen IP-Adresse eines privaten Clusters generieren.

Authentifizierung für kubectl

Alle GKE-Cluster sind so konfiguriert, dass sie die Identitäten von Google Cloud-Nutzern und -Dienstkonten akzeptieren. Dabei werden die von kubectl bereitgestellten Anmeldedaten validiert und die mit der Nutzer- oder Dienstkontoidentität verknüpfte E-Mail-Adresse abgerufen. Die Anmeldedaten dieser Konten müssen daher für die Authentifizierung den OAuth-Bereich userinfo.email enthalten.

Wenn Sie gcloud zum Einrichten der kubeconfig Ihrer Umgebung für einen neuen oder einen bestehenden Cluster verwenden, weist gcloud dem kubectl-Befehlszeilentool die gleichen Anmeldedaten wie für gcloud zu. Wenn Sie beispielsweise gcloud auth login verwenden, werden kubectl Ihre persönlichen Anmeldedaten einschließlich des Bereichs userinfo.email bereitgestellt. Der GKE-Cluster kann dadurch den Client von kubectl authentifizieren.

Alternativ können Sie festlegen, dass kubectl während der Ausführung auf einer Compute Engine-Instanz die Anmeldedaten eines Google Cloud-Dienstkontos verwendet. Der userinfo.email-Bereich ist jedoch nicht standardmäßig in den von Compute Engine-Instanzen erstellten Anmeldedaten enthalten. Sie müssen diesen Bereich daher explizit einfügen. Beim Erstellen der Compute Engine-Instanz können Sie dies beispielsweise mit dem Flag --scopes tun.

Authentifizierte Nutzer oder Google Cloud-Dienstkonten müssen außerdem autorisiert werden, um Aktionen an GKE-Clustern ausführen zu können. Weitere Informationen zum Konfigurieren der Autorisierung finden Sie unter Rollenbasierte Zugriffssteuerung.

Informationen zu unterstützten Authentifizierungsmethoden beim Herstellen einer Verbindung zum Kubernetes API-Server finden Sie unter Authentifizierung beim Kubernetes API-Server.

Aktuellen Kontext für kubectl ansehen

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

kubectl config current-context

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 für den Cluster einen Eintrag in kubeconfig generieren.

kubeconfig-Eintrag generieren

Zum Ausführen von kubectl-Befehlen für einen Cluster, der in der Cloud Console, auf einem anderen Computer oder von einem anderen Mitglied des Projekts erstellt wurde, müssen Sie in Ihrer Umgebung einen kubeconfig-Eintrag generieren.

Mit dem folgenden Befehl generieren Sie einen Eintrag in kubeconfig:

gcloud container clusters get-credentials CLUSTER_NAME

Ersetzen Sie CLUSTER_NAME durch den Namen des Clusters.

Für diesen Befehl benötigen Sie die Berechtigung container.clusters.get. Die IAM-Rolle mit den geringsten Berechtigungen, die diese Berechtigung bietet, ist container.clusterViewer.

Der Eintrag in kubeconfig enthält entweder:

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

Beim Ausführen von get-credentials können Sie festlegen, dass --internal-ip die interne IP-Adresse eines privaten Clusters in kubeconfig schreibt:

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

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

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 my-cluster

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

Sie können einzelne kubectl-Befehle für einen bestimmten Cluster ausführen. Dazu übergeben Sie den Namen des Clusters wie in kubeconfig angegeben als Argument für das Flag --cluster.

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. Führen Sie den folgenden Befehl aus, um die Anwendung in my-new-cluster bereitzustellen, 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

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.

Nächste Schritte

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