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.
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ä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 Streamingbefehle und unterliegen zusätzlichen Anforderungen:
attachcpexecport-forward
Beachten Sie folgende Anforderungen:
Für die Befehle
attach,cpundexecmuss die Clusterversion 1.30 oder höher sein. Für den Befehlport-forwardmuss die Clusterversion 1.31 oder höher sein.Der
kubectl-Client muss Version 1.31 oder höher haben.Sehen Sie sich die Ausgabe des Befehls
kubectl versionan, um die Clientversion zu prüfen. Informationen zum Installieren einer neueren Version vonkubectlfinden Sie unter Tools installieren.
Nutzer und Dienstkonten mit der IAM-Rolle roles/gkehub.gatewayAdmin und der cluster-admin ClusterRole haben die erforderlichen Berechtigungen zum Ausführen der Befehle attach, cp, exec und port-forward. Wenn Nutzern und Dienstkonten eine benutzerdefinierte IAM-Rolle oder benutzerdefinierte RBAC-Rolle zugewiesen wurde, müssen Sie möglicherweise zusätzliche Berechtigungen erteilen. Weitere Informationen finden Sie in den folgenden Abschnitten.
Bei Bedarf zusätzliche Berechtigungen erteilen
Die IAM-Berechtigung gkehub.gateway.stream ist erforderlich, um die Befehle attach, cp, exec und port-forward über das Connect-Gateway auszuführen. Diese Berechtigung ist in roles/gkehub.gatewayAdmin enthalten.
Nutzern, die keine Projektinhaber sind, oder Nutzern oder Dienstkonten, denen die Berechtigung roles/gkehub.gatewayAdmin im Projekt nicht zugewiesen wurde, müssen Sie entweder die Berechtigung roles/gkehub.gatewayAdmin zuweisen oder eine benutzerdefinierte Rolle erstellen, die die anderen erforderlichen Rollen und die Berechtigung gkehub.gateway.stream enthält. Informationen zum Erstellen einer benutzerdefinierten Rolle finden Sie in der IAM-Dokumentation unter Benutzerdefinierte Rollen erstellen und verwalten.
Bei Bedarf zusätzliche RBAC-Richtlinien erstellen und anwenden
Nutzer und Dienstkonten mit der Rolle cluster-admin ClusterRole haben die erforderlichen Berechtigungen zum Ausführen der Befehle attach, cp, exec und port-forward.
Zum Ausführen der Befehle sind mindestens die folgenden Regeln erforderlich:
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: User
name: EMAIL # Specify the user that should have stream access
namespace: NAMESPACE # Specify the namespace
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 nsfehlschlägt. Für diesen Fehler gibt es mehrere mögliche Gründe. Führen Sie Ihrekubectl-Befehle im detaillierten Modus aus, um weitere Details zu sehen, beispielsweisekubectl 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-connectauf dem Cluster vorhanden ist. Wenn der Namespacegke-connectauf 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
kubeconfigeine 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 Gatewaykubeconfigzu generieren. Bearbeiten Sie die Dateikubeconfignicht 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.gatewayReaderoderroles/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-pluginund führen Siegcloud container fleet memberships get-credentials MEMBERSHIP_NAMEmit 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-agentnoch einmal aus.Die Größe der Gruppen, die unter der Gruppe
gke-security-groupszurü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“
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 Sie keine RBAC-Berechtigungen haben. 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 wird unter dem 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.
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.