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:

  • Die neueste Version der Google Cloud CLI, dem Befehlszeilentool für die Interaktion mit Google Cloud.
  • kubectl

  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:

• Rufen Sie die kubeconfig-Datei für den Cluster ab: Connect Gateway Reader (roles/gkehub.gatewayReader)
• kubectl-CLI-Befehle ausführen: Connect Gateway-Administrator (roles/gkehub.gatewayAdmin)

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

Die Rolle „Connect Gateway Admin“ (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.

Melden Sie sich in Ihrem Google Cloud -Konto an.

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äten von Dienstkonten. 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.

Gateway des Clusters kubeconfig abrufen

Verwenden Sie den folgenden Befehl, um den kubeconfig abzurufen, den Sie für die Interaktion mit dem angegebenen Cluster benötigen:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ersetzen Sie MEMBERSHIP_NAME durch den Namen der Flottenmitgliedschaft Ihres Clusters.

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 Dienstkontos 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 und VMware: Der Name der Mitgliedschaft entspricht dem Clusternamen.

• 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-Befehle „exec“, „cp“, „attach“ und „port-forward“

Die folgenden kubectl-Befehle sind Streaming-Befehle und unterliegen zusätzlichen Anforderungen:

• attach
• cp
• exec
• port-forward

Damit Sie diese Befehle ausführen können, müssen Sie die folgenden Anforderungen erfüllen:

• Cluster müssen Version 1.30 oder höher für die Befehle attach, cp und exec und Version 1.31 oder höher für den Befehl port-forward 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 benötigen den folgenden zusätzlichen Zugriff auf die Kubernetes API über IAM oder RBAC:

  • IAM: Weisen Sie eine Rolle zu, die die Berechtigung gkehub.gateway.stream 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 API-Unterressourcen pods/exec, pods/portforward und pods/attach 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 das RoleBinding.
    • EMAIL: Die E-Mail-Adresse der Gruppe, die Streamzugriff haben soll, wenn der Cluster RBAC mit Gruppen unterstützt.

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

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, beispielsweise 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 Connect Agent die Verbindung verliert oder nicht richtig installiert ist (nur bei Clustern außerhalb von 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 Datei kubeconfig 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 hat nicht die erforderlichen Berechtigungen zum Ausführen des Vorgangs, wenn Google Groups oder Drittanbieter-Support verwendet wird: Eine Anleitung zum Prüfen von Logs, die sich auf Identitätsinformationen beziehen, 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 der Google Cloud CLI noch einmal aus.
• Verbindungen zum Gateway schlagen bei ä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 Mitgliedschaftsregistrierung 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. Um dieses Problem zu beheben, aktualisieren Sie entweder Ihren Google Cloud CLI-Client auf eine neuere Version oder führen Sie den Befehl zur Mitgliedschaftsregistrierung mit dem Flag --install-connect-agent noch einmal aus.
• Die Größe der Gruppen, die unter der Gruppe gke-security-groups zurückgegeben werden, überschreitet das Größenlimit für HTTP-Header von 8 KB. Gruppenhierarchie neu organisieren und noch einmal versuchen: Es gibt zwar kein festes Limit für die Anzahl der Gruppen, aber lange Gruppennamen können dazu führen, dass die Anfrage das Größenlimit für HTTP-Header von 8 KB überschreitet. Dies kann zu Fehlern führen, die eine Umstrukturierung der Gruppenhierarchie erforderlich machen.

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

Hinweis :In kubectl-Versionen vor 1.32 werden nicht genügend Informationen für das Debugging protokolliert. Wir empfehlen, ein Upgrade Ihres kubectl-Clients auf Version 1.32 oder höher durchzuführen.

Der Fehler, der beim Ausführen 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 erhalten möchten, verwenden Sie die kubectl-Clientversion 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, 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 diese Funktion 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“.

Erforderliche RBAC-Berechtigungen fehlen

Wenn die Fehlermeldung ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden... enthält, bedeutet das, dass Ihnen RBAC-Berechtigungen fehlen. 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: Das Kontingent für aktive Streams des Gateways ist erschöpft

Pro Flotten-Hostprojekt sind maximal zehn aktive Streams zulässig. Das ist im connectgateway.googleapis.com/active_streams-Kontingent definiert. Eine Anleitung zum Verwalten Ihrer Kontingente finden Sie unter Kontingente aufrufen und verwalten.

Fehlermeldung „generic::failed_precondition: error encountered within the cluster“ (generic::failed_precondition: Fehler im Cluster aufgetreten)

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

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

Das Log, nach dem Sie im Connect-Agent suchen müssen, ist failed to create the websocket connection....

Fehlermeldung „generic::failed_precondition: connection to Agent failed/terminated“ (generic::failed_precondition: Verbindung zum Agent fehlgeschlagen/beendet)

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 nach etwa 20 bis 30 Minuten auftritt, ist das eine erwartete Einschränkung aus Sicherheitsgründen. Die Verbindung muss neu hergestellt werden.

kubectl --raw-Fehlerbehebung

Wenn Sie einen gekürzten Endpunkt wie kubectl get --raw /version verwenden, kann der folgende Fehler auftreten: 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 Ihrem 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.