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 dieses Leitfadens 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 von 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 Cloud verwenden, sind diese Tools für Sie installiert.
Achten Sie darauf, dass die gcloud CLI für die Verwendung mit Ihrem Projekt initialisiert wurde.
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 mit dem angegebenen Cluster interagieren müssen. Ersetzen Sie dabei MEMBERSHIP_NAME
durch den Mitgliedschaftsnamen der Flotte für Ihren Cluster. Dieser Befehl gibt ein spezielles Connect-gateway-spezifisches kubeconfig
zurück, über das Sie eine Verbindung zum Cluster über das Gateway herstellen können.
# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
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. Weitere Informationen dazu, wie Sie Nutzern erlauben, die Identität eines Dienstkontos zu übernehmen, finden Sie unter Zugriff auf Dienstkonten verwalten.
# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
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
Die folgenden kubectl
-Befehle werden vom Gateway nicht unterstützt:
exec
proxy
port-forward
attach
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 ein einfacher Befehl wie
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, 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 ordnungsgemäß installiert wird. Um dieses Problem zu beheben, müssen Sie prüfen, ob der Namespace
gke-connect
auf dem Cluster vorhanden ist. Ist dies nicht der Fall, finden Sie weitere Informationen unter Cluster bei Google Cloud CLI registrieren. Wenn der Namespacegke-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 Gatewaykubeconfig
zu generieren. Bearbeiten Sie die Dateikubeconfig
nicht manuell, was 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
oderroles/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 ist nicht berechtigt, den Vorgang auszuführen, wenn Google Groups oder der Support von Drittanbietern verwendet werden: Unter GKE Identity Service-Logs erfassen finden Sie eine Anleitung zum Prüfen von Logs im Zusammenhang mit von Identitätsinformationen.
- 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 Siegcloud container fleet memberships get-credentials MEMBERSHIP_NAME
mit der neuesten Version der 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 für das Funktionieren des Gateways nicht mehr erforderlich und wird daher nicht standardmäßig bei der Mitgliedschaftsregistrierung installiert. Bei älteren 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 älteren 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.
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.