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 des Cloud SDK, einschließlich gcloud, 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 das gcloud-Befehlszeilentool zur 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 Cloud SDK-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 aufrufen:

gcloud container hub memberships list

Hier werden alle Cluster aus Ihrer Umgebung aufgelistet, einschließlich der Mitgliedernamen und externen IDs. Jeder Cluster in einer Umgebung hat einen eindeutigen Namen. 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 kubeconfig zum Interagieren mit dem angegebenen Cluster zu erhalten. Ersetzen Sie dabei MEMBERSHIP_NAME durch den Umgebungsnamen Ihres Clusters. 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 beta container hub memberships get-credentials MEMBERSHIP_NAME

Wenn Sie ein Dienstkonto anstelle Ihres eigenen Google Cloud-Kontos verwenden möchten, verwenden Sie gcloud config, um auth/impersonate_service_account auf die E-Mail-Adresse des Dienstkontos festzulegen. Weitere Informationen dazu, wie Sie Nutzern erlauben, die Identität eines Dienstkontos zu übernehmen, finden Sie unter Identitätswechsel für 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 beta container hub 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

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 "Namespaces": 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, beispielsweise kubectl get ns -v 10.
  • 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 Cloud SDK-Version, die Sie verwenden, die neueste Version ist, und versuchen Sie dann, das Gateway kubeconfig zu generieren. Bearbeiten Sie die Datei kubeconfig 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 role/gkehub.gatewayAdmin, um die API verwenden zu können. Weitere Informationen finden Sie im Leitfaden zur Einrichtung des Gateways unter IAM-Berechtigungen erteilen.
  • 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-Richtlinien 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-Richtlinien konfigurieren in der Gateway-Einrichtungsanleitung finden Sie ein Beispiel zum Hinzufügen eines Nutzers zum entsprechenden ClusterRole.
  • Connect-Agent ist fehlerhaft: Sehen Sie auf der Seite zur Fehlerbehebung bei Verbindungsproblemen nach, ob Ihr Cluster verbunden ist.

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.