Connect-Gateway verwenden

Auf dieser Seite erfahren Sie, wie Sie das Connect-Gateway verwenden, um eine Verbindung zu einem registrierten Cluster herzustellen. Machen Sie sich vor dem Lesen dieser Seite mit den Konzepten in unserer Übersicht vertraut. In dieser Anleitung wird davon ausgegangen, dass Ihr Projektadministrator das Gateway bereits eingerichtet und Ihnen die erforderlichen Rollen und Berechtigungen zugewiesen hat.

Hinweis

  • Prüfen Sie, ob die folgenden Befehlszeilentools installiert sind:

    Wenn Sie Cloud Shell als Shell-Umgebung für die Interaktion mit Google Cloudverwenden, sind diese Tools für Sie installiert.

  • Achten Sie darauf, dass die gcloud CLI für die Verwendung mit Ihrem Projekt initialisiert wurde.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Clusterprojekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung des Connect-Gateways zum Herstellen einer Verbindung zu Clustern und zum Ausführen von Befehlen benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Die Rolle „Connect Gateway-Administrator“ (roles/gkehub.gatewayAdmin) ist die einzige vordefinierte Rolle, die die Berechtigung gkehub.gateway.stream enthält. Diese ist erforderlich, um kubectl-CLI-Befehle wie attach, exec, port-forward und cp auszuführen.

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

In Ihrem Google Cloud Konto anmelden

Sie können Ihr eigenes Google Cloud Konto oder ein Google Cloud Dienstkonto verwenden, um über die Gateway API mit verbundenen Clustern zu interagieren.

Folgen Sie der Anleitung unter Google Cloud CLI-Tools autorisieren, um sich in Ihrem Nutzerkonto anzumelden. Das Connect-Gateway unterstützt Identitätsübernahme des Dienstkontos. Wenn Sie also in Ihrem eigenen Nutzerkonto angemeldet sind, können Sie ein Dienstkonto verwenden, um mit Clustern zu interagieren, wie in den folgenden Abschnitten gezeigt.

Registrierten Cluster auswählen

Wenn Sie den Namen des Clusters, auf den Sie zugreifen möchten, nicht kennen, können Sie mit dem folgenden Befehl alle aktuell registrierten Cluster in der Flotte aufrufen:

gcloud container fleet memberships list

Hier werden alle Cluster aus Ihrer Flotte aufgelistet, einschließlich der Mitgliedschaftsnamen und externen IDs. Jeder Cluster in einer Flotte hat einen eindeutigen Mitgliedschaftsnamen. Bei GKE-Clustern stimmt der Name der Mitgliedschaft in der Regel mit dem Namen überein, den Sie beim Erstellen des Clusters vergeben haben, sofern der Name des Clusters bei der Registrierung nicht eindeutig war.

kubeconfig des Cluster-Gateways abrufen

Verwenden Sie den folgenden Befehl, um die kubeconfig abzurufen, die Sie zum Interagieren mit dem angegebenen Cluster benötigen:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ersetzen Sie MEMBERSHIP_NAME durch den Mitgliedschaftsnamen der Flotte für Ihren Cluster.

Dieser Befehl gibt eine spezielle Connect-Gateway-spezifische kubeconfig zurück, mit der Sie über das Connect-Gateway eine Verbindung zum Cluster herstellen können.

Wenn Sie ein Dienstkonto anstelle Ihres eigenen Google Cloud Kontos verwenden möchten, legen Sie mit gcloud config die E-Mail-Adresse des Dienst kontos auf auth/impersonate_service_account fest.

Führen Sie die folgenden Befehle aus, um die Clusteranmeldedaten abzurufen, die für die Interaktion mit dem Connect-Gateway über ein Dienstkonto verwendet werden. Beachten Sie Folgendes:

  • Google Distributed Cloud-Cluster (nur Software) auf Bare-Metal-Servern und VMware: Der Mitgliedschaftsname ist derselbe wie der Clustername.

  • GKE on AWS: Verwenden Sie gcloud container aws clusters get-credentials.

  • GKE on Azure: Verwenden Sie gcloud container azure clusters get-credentials.

Weitere Informationen dazu, wie Sie Nutzern erlauben, die Identität eines Dienstkontos zu übernehmen, finden Sie unter Zugriff auf Dienstkonten verwalten.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ersetzen Sie SA_EMAIL_ADDRESS durch die E-Mail-Adresse des Dienstkontos. Weitere Informationen dazu, wie Sie Nutzern erlauben, die Identität eines Dienstkontos zu übernehmen, finden Sie unter Zugriff auf Dienstkonten verwalten.

Befehle für den Cluster ausführen

Sobald Sie die erforderlichen Anmeldedaten haben, können Sie mitkubectl odergo-client wie bei jedem Kubernetes-Cluster Befehle ausführen. Ihre Ausgabe sollte in etwa so aussehen:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

`kubectl exec/cp/attach/port-forward`-Befehle

Die folgenden kubectl-Befehle sind Streamingbefehle und haben zusätzliche Anforderungen:

  • attach
  • cp
  • exec
  • port-forward

Um diese Befehle auszuführen, müssen die folgenden Anforderungen erfüllt sein:

  • Cluster müssen für die Befehle attach, cp und exec Version 1.30 oder höher und für den Befehl port-forward Version 1.31 oder höher haben.

  • Der kubectl-Client muss Version 1.31 oder höher haben. Die Clientversion finden Sie in der Ausgabe des Befehls kubectl version. Informationen zum Installieren einer neueren Version von kubectl, finden Sie unter Tools installieren.

  • Nutzer und Dienstkonten müssen über IAM oder RBAC den folgenden zusätzlichen Zugriff auf die Kubernetes API haben:

    • IAM: Weisen Sie eine Rolle zu, die die gkehub.gateway.stream Berechtigung enthält. Die vordefinierte Rolle roles/gkehub.gatewayAdmin enthält diese Berechtigung. Sie können diese Berechtigung auch einer benutzerdefinierten Rolle zuweisen.

    • RBAC: Weisen Sie eine Rolle oder ClusterRole zu, die get Zugriff auf die pods/exec, pods/portforward und pods/attach API-Unterressourcen enthält, wie im folgenden Beispiel für Rolle und RoleBinding:

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE # Specify the namespace
roleRef:
  apiGroup: "rbac.authorization.k8s.io"
  kind: Role
  name: stream-role
subjects:
- kind: Group
  name: EMAIL # Specify the group that should have stream access

      Ersetzen Sie Folgendes:

      • NAMESPACE: Der Namespace für die Rolle und RoleBinding.
      • EMAIL: Die E-Mail-Adresse der Gruppe , die Streamingzugriff haben soll, wenn der Cluster RBAC mit Gruppenunterstützt.

      Die Standard-ClusterRole cluster-admin enthält ebenfalls diese Berechtigungen.

Fehlerbehebung

Wenn Sie Probleme haben, über das Gateway eine Verbindung zu einem Cluster herzustellen, können Sie oder Ihr Administrator nach den folgenden häufigen Problemen suchen.

  • Der Server hat keinen Ressourcentyp: Diese Fehlermeldung wird möglicherweise angezeigt, wenn der Befehl kubectl get ns fehlschlägt. Für diesen Fehler gibt es mehrere mögliche Gründe. Führen Sie Ihre kubectl Befehle im detaillierten Modus aus, um weitere Details zu sehen, z. B. kubectl get ns -v 10.
  • Es können keine aktiven Verbindungen für Cluster gefunden werden(Projekt: 12345, Mitgliedschaft: my-cluster): Dieser Fehler wird möglicherweise angezeigt, wenn der Connect-Agent die Verbindung verliert oder nicht ordnungsgemäß installiert ist (nur bei Clustern außerhalb Google Cloud ). Um dieses Problem zu beheben, müssen Sie prüfen, ob der Namespace gke-connect auf dem Cluster vorhanden ist. Wenn der Namespace gke-connect auf dem Cluster vorhanden ist, lesen Sie den Abschnitt Fehlerbehebung bei der Verbindung, um die Verbindungsprobleme zu beheben.
  • Die angeforderte URL wurde auf diesem Server nicht gefunden: Dieser Fehler kann auftreten, wenn kubeconfig eine falsche Serveradresse enthält. Achten Sie darauf, dass die verwendete Version von Google Cloud CLI die neueste Version ist, und versuchen Sie noch einmal, das Gateway kubeconfig zu generieren. Bearbeiten Sie die kubeconfig-Datei nicht manuell, da dies zu unerwarteten Fehlern führen kann.
  • Die Nutzeridentität reicht nicht aus, um die Gateway API zu verwenden: Sie benötigen die Rolle roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader oder roles/gkehub.gatewayEditor, um die API verwenden zu können. Weitere Informationen finden Sie im Leitfaden zur Einrichtung des Gateways unter Nutzern IAM-Rollen zuweisen.
  • Der Connect-Agent ist nicht berechtigt, Nutzeranfragen zu senden: Der Connect-Agent muss Anfragen in Ihrem Namen weiterleiten, die mithilfe einer Identitätsrichtlinie im Cluster angegeben wurden. Unter RBAC-Autorisierung konfigurieren im Leitfaden zur Einrichtung von Gateways finden Sie ein Beispiel zum Hinzufügen eines Nutzers zur Rolle gateway-impersonate.
  • Die Nutzeridentität verfügt nicht über ausreichende RBAC-Berechtigungen zum Ausführen des Vorgangs: Sie benötigen die entsprechenden Berechtigungen für den Cluster, um die ausgewählten Vorgänge auszuführen. Im Artikel RBAC-Autorisierung konfigurieren in der Gateway-Einrichtungsanleitung finden Sie ein Beispiel zum Hinzufügen eines Nutzers zum entsprechenden ClusterRole.
  • Die Nutzeridentität verfügt nicht über ausreichende Berechtigungen zum Ausführen des Vorgangs bei Verwendung von Google Groups oder Drittanbieter-Support: Eine Anleitung zum Prüfen von Logs mit Identitätsinformationen finden Sie unter GKE Identity Service-Logs erfassen.
  • Connect-Agent ist fehlerhaft: Sehen Sie auf der Seite zur Fehlerbehebung bei Verbindungsproblemen nach, ob Ihr Cluster verbunden ist.
  • Ausführbare Datei gke-gcloud-auth-plugin nicht gefunden oder Kein Auth-Anbieter für Name GCP gefunden: In kubectl-Versionen ab 1.26 wird dieser Fehler möglicherweise aufgrund von Änderungen an der kubectl-Authentifizierung ab GKE v1.26 angezeigt. Installieren Sie gke-gcloud-auth-plugin und führen Sie gcloud container fleet memberships get-credentials MEMBERSHIP_NAME mit der neuesten Version von Google Cloud CLI noch einmal aus.
  • Verbindungen zum Gateway schlagen mit älteren Versionen der Google Cloud CLI fehl: Bei GKE-Clustern ist der Connect-Agent nicht mehr erforderlich, damit das Gateway funktioniert. Er wird daher bei der Registrierung der Mitgliedschaft nicht standardmäßig installiert. Bei früheren Versionen der Google Cloud CLI (399.0.0 und niedriger) wird davon ausgegangen, dass der Connect-Agent im Cluster vorhanden ist. Der Versuch, das Gateway mit diesen früheren Versionen zu verwenden, kann bei Clustern fehlschlagen, die mit einer neueren Version der Google Cloud CLI registriert werden. Aktualisieren Sie zur Behebung dieses Problems entweder Ihren Google Cloud CLI-Client auf eine neuere Version oder führen Sie den Befehl zur Registrierung der Mitgliedschaft mit dem Flag --install-connect-agent noch einmal aus.
  • Die Größe der unter der Gruppe gke-security-groups zurückgegebenen Gruppen überschreitet das Limit von 8 KB für die HTTP-Headergröße. Organisieren Sie die Gruppenhierarchie neu und versuchen Sie es noch einmal: Die Anzahl der Gruppen ist zwar nicht begrenzt, aber lange Gruppennamen können dazu führen, dass die Anfrage das Limit von 8 KB für die HTTP-Headergröße überschreitet und Fehler auftreten, die eine Umstrukturierung der Gruppenhierarchie erforderlich machen.

Fehlerbehebung für `kubectl exec/cp/attach/port-forward`

Der Fehler, der bei der Ausführung des Befehls zurückgegeben wird, ist oft ein allgemeiner 400 Bad Request-Fehler, der nicht aussagekräftig genug ist, um das Problem zu beheben. Wenn Sie detailliertere Fehlermeldungen zurückgeben möchten, verwenden Sie den kubectl Client Version 1.32 oder höher, um den Befehl mit einer Ausführlichkeit von Stufe 4 oder höher auszuführen, z. B.: kubectl exec -v 4 ....

Suchen Sie in den zurückgegebenen Logs nach dem Log, das die folgenden Antworten enthält:

  • Für den Befehl kubectl exec/cp/attach: RemoteCommand fallback:
  • Für den Befehl kubectl port-forward: fallback to secondary dialer from primary dialer err:

Informationen zur Fehlerbehebung bei einigen der häufigsten Fehlermeldungen, die Sie vom Befehl kubectl exec -v 4 ... erhalten können, finden Sie im folgenden Abschnitt.

Fehlende IAM-Berechtigungen

Wenn die Fehlermeldung generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, enthält, haben Sie möglicherweise nicht die erforderlichen IAM Berechtigungen zum Ausführen des Befehls. Für dieses Feature benötigen Nutzer die IAM-Berechtigung gkehub.gateway.stream, die standardmäßig in der Rolle roles/gkehub.gatewayAdmin enthalten ist. Eine Anleitung finden Sie im Abschnitt IAM-Berechtigungen.

Fehlende erforderliche RBAC-Berechtigungen

Wenn die Fehlermeldung ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden... enthält, fehlen Ihnen RBAC-Berechtigungen. Sie benötigen eine Reihe von RBAC-Berechtigungen im Cluster, um diese kubectl-Befehle auszuführen. Weitere Informationen zum Einrichten der erforderlichen RBAC-Berechtigungen finden Sie unter Bei Bedarf zusätzliche RBAC-Richtlinien erstellen und anwenden.

Fehlermeldung „generic::resource_exhausted: Gateway's active_streams quota exhausted“

Es gilt ein Kontingentlimit von 10 aktiven Streams pro Flotten-Hostprojekt. Dieses Limit ist im Kontingent connectgateway.googleapis.com/active_streams definiert. Eine Anleitung zum Verwalten Ihrer Kontingente finden Sie unter Kontingente aufrufen und verwalten.

Fehlermeldung „generic::failed_precondition: error encountered within the cluster“

Wenn Sie den Fehler generic::failed_precondition: error encountered within the cluster erhalten, prüfen Sie die Connect-Agent-Logs im Cluster, um die Ursache zu ermitteln:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Suchen Sie im Connect-Agent-Log nach failed to create the websocket connection....

Fehlermeldung „generic::failed_precondition: connection to Agent failed/terminated“

Wenn dieser Fehler sofort beim Ausführen des Befehls auftritt, liegt ein Problem mit der Verbindung des Clusters zu Google vor. Weitere Informationen finden Sie im allgemeinen Leitfaden zur Fehlerbehebung.

Wenn dieser Fehler auftritt, nachdem die Sitzung etwa 20 bis 30 Minuten aktiv war, ist dies aus Sicherheitsgründen eine erwartete Einschränkung. Die Verbindung muss wiederhergestellt werden.

Fehlerbehebung für kubectl --raw

Die Verwendung eines gekürzten Endpunkts (z. B. kubectl get --raw /version) kann zu folgendem Fehler führen: Error from server (NotFound): the server could not find the requested resource. Sie müssen die vollständige Serveradresse angeben.

Rufen Sie den Endpunkt aus Ihrer kubeconfig ab:

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

Verwenden Sie dann den Endpunkt für Ihren Befehl, z. B. mit /version:

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

Nächste Schritte

  • Ein Beispiel für die Verwendung des Connect-Gateways als Teil Ihrer DevOps-Automatisierung finden Sie in unserer Anleitung In Cloud Build einbinden.