In dieser Anleitung erfahren Sie, wie Sie mit dem Extensible Service Proxy V2 (ESPv2) einen einfachen gRPC in einem Kubernetes-Cluster bereitstellen, der nicht in Google Cloud ausgeführt wird. Dafür wird in der Anleitung die Python-Version des Beispiels bookstore-grpc
verwendet. gRPC-Beispiele in anderen Sprachen finden Sie unter Weitere Informationen.
In der Anleitung werden vorkonfigurierte Container-Images des Beispielcodes und des ESPv2 verwendet, die in Artifact Registry gespeichert sind. Wenn Sie nicht mit Containern vertraut sind, finden Sie weitere Informationen auf den folgenden Seiten:
Eine Übersicht über Cloud Endpoints finden Sie in den Abschnitten Über Cloud Endpoints und Architekturübersicht zu Cloud Endpoints.
Ziele
Orientieren Sie sich beim Durcharbeiten der Anleitung an der folgenden Aufgabenliste. Alle Aufgaben sind erforderlich, um Anfragen sicher an die API senden zu können.
- Richten Sie ein Google Cloud-Projekt ein und laden Sie die erforderliche Software herunter. Siehe Vorbereitung.
- Dateien aus dem Beispiel
bookstore-grpc
kopieren und konfigurieren. Siehe Cloud Endpoints konfigurieren. - Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
- Anmeldedaten für Ihren Endpoints-Dienst erstellen. Siehe Anmeldedaten für den Dienst erstellen.
- Ein Back-End für die API erstellen und die API bereitstellen. Siehe API-Back-End bereitstellen.
- Rufen Sie die externe IP-Adresse des Diensts ab. Siehe Externe IP-Adresse des Diensts abrufen.
- Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
- Vermeiden Sie Gebühren, die Ihrem Google Cloud-Konto in Rechnung gestellt werden. Siehe Bereinigen.
Kosten
In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:
Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.
Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.
Hinweise
Es wird vorausgesetzt, dass Sie bereits Minikube oder einen Kubernetes-Cluster eingerichtet haben. Weitere Informationen finden Sie in der Kubernetes-Dokumentation.
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Notieren Sie sich die Google Cloud-Projekt-ID, da sie später benötigt wird.
- Installieren und initialisieren Sie die gcloud CLI.
- Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten.
gcloud components update
- Die Google Cloud CLI (
gcloud
) muss für den Zugriff auf Ihre Daten und Dienste auf Google Cloud berechtigt sein: Ein neuer Tab wird geöffnet. Wählen Sie dort ein Konto aus.gcloud auth login
- Legen Sie für das Standardprojekt Ihre Projekt-ID fest:
gcloud config set project YOUR_PROJECT_ID
Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.
Wenn Sie weitere Google Cloud-Projekte mit
gcloud
verwalten möchten, lesen Sie gcloud CLI-Konfigurationen verwalten. - Installieren Sie
kubectl
:gcloud components install kubectl
- Rufen Sie die neuen Nutzeranmeldedaten ab, die als Standardanmeldedaten für Anwendungen verwendet werden sollen.
Die Nutzeranmeldedaten werden zur Autorisierung von
kubectl
verwendet.gcloud auth application-default login
- Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
- Installieren Sie gRPC und die gRPC-Tools. Informationen dazu finden Sie in der Schnellstart-Anleitung für gRPC Python.
Endpoints konfigurieren
Das Beispiel bookstore-grpc
enthält die Dateien, die Sie lokal kopieren und konfigurieren müssen.
- Erstellen Sie aus der Datei
.proto
Ihres Dienstes eine abgeschlossene protobuf-Deskriptordatei:- Speichern Sie eine Kopie von
bookstore.proto
aus dem Beispiel-Repository. Diese Datei definiert die API für den Bookstore-Dienst. - Erstellen Sie das folgende Verzeichnis:
mkdir generated_pb2
- Erstellen Sie die Deskriptordatei
api_descriptor.pb
mit dem Protokollpuffercompilerprotoc
. Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem Siebookstore.proto
gespeichert haben:python -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto
Im vorherigen Befehl ist
--proto_path
auf das aktuelle Arbeitsverzeichnis festgelegt. Wenn Sie in Ihrer gRPC-Build-Umgebung ein anderes Verzeichnis für.proto
-Eingabedateien verwenden, ändern Sie--proto_path
entsprechend, sodass der Compiler das Verzeichnis mit der gespeichertenbookstore.proto
-Datei durchsucht.
- Speichern Sie eine Kopie von
- Erstellen Sie eine gRPC API-Konfigurationsdatei in YAML:
- Speichern Sie eine Kopie der Datei
api_config.yaml
. Diese Datei definiert die gRPC API-Konfiguration für den Bookstore-Dienst. - Ersetzen Sie MY_PROJECT_ID in Ihrer Datei
api_config.yaml
durch Ihre Google Cloud-Projekt-ID. Beispiel:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
Beachten Sie, dass der Wert des Feldes
apis.name
in dieser Datei exakt mit dem vollständig qualifizierten API-Namen aus der Datei.proto
übereinstimmt. Andernfalls würde die Bereitstellung nicht funktionieren. Der Bookstore-Dienst ist inbookstore.proto
im Paketendpoints.examples.bookstore
definiert. Der vollständig qualifizierte API-Name lautetendpoints.examples.bookstore.Bookstore
, genau wie er in der Dateiapi_config.yaml
angezeigt wird.apis: - name: endpoints.examples.bookstore.Bookstore
- Speichern Sie eine Kopie der Datei
Weitere Informationen finden Sie unter Endpoints konfigurieren.
Endpoints-Konfiguration bereitstellen
Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy
bereitgestellt. Dieser Befehl verwendet Service Infrastructure, die grundlegende Dienstplattform von Google. Sie wird von Endpoints und anderen Diensten verwendet, um APIs und Dienste zu erstellen und zu verwalten.
- Sie müssen sich in dem Verzeichnis befinden, in dem die Dateien
api_descriptor.pb
undapi_config.yaml
liegen. - Vergewissern Sie sich, dass das aktuell vom
gcloud
-Befehlszeilentool verwendete Standardprojekt das Google Cloud-Projekt ist, für das Sie die Endpoints-Konfiguration bereitstellen möchten. Überprüfen Sie anhand der vom folgenden Befehl zurückgegebenen Projekt-ID, ob der Dienst im richtigen Projekt erstellt wird.gcloud config list project
Wenn Sie das Standardprojekt ändern müssen, führen Sie den folgenden Befehl aus:
gcloud config set project YOUR_PROJECT_ID
- Stellen Sie die Datei
proto descriptor
und die Konfigurationsdatei mithilfe der Google Cloud CLI bereit:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Nach Abschluss der Bereitstellung erhalten Sie eine Meldung, die in etwa so aussieht:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID ist die eindeutige Endpoints-Dienstkonfigurations-ID, die von der Bereitstellung erstellt wird. Beispiel:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
Im obigen Beispiel ist
2017-02-13r0
die Dienstkonfigurations-ID undbookstore.endpoints.example-project.cloud.goog
der Dienstname. Die Dienstkonfigurations-ID besteht aus einem Datumsstempel und einer Überarbeitungsnummer. Wenn Sie die Endpoints-Konfiguration am selben Tag noch einmal bereitstellen, erhöht sich die Überarbeitungsnummer in der Dienstkonfigurations-ID.
Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Endpoints-Konfigurationsbereitstellung.
Weitere Informationen finden Sie unter Endpoints-Konfiguration bereitstellen.
Erforderliche Dienste prüfen
Für Endpoints und ESP müssen mindestens die folgenden Google-Dienste aktiviert sein:Name | Titel |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
In der Regel werden die erforderlichen Dienste mit dem Befehl gcloud endpoints services deploy
aktiviert. Unter folgenden Umständen kann es vorkommen, dass der Befehl gcloud
erfolgreich ausgeführt wird, die erforderlichen Dienste jedoch nicht aktiviert werden:
Wenn Sie eine Drittanbieteranwendung wie Terraform verwendet haben und Sie diese Dienste nicht hinzufügen.
Wenn Sie die Endpoints-Konfiguration für ein vorhandenes Google Cloud-Projekt bereitgestellt haben, in dem diese Dienste explizit deaktiviert wurden.
Prüfen Sie mit dem folgenden Befehl, ob die erforderlichen Dienste aktiviert sind:
gcloud services list
Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Aktivieren Sie auch Ihren Endpoints-Dienst:
gcloud services enable ENDPOINTS_SERVICE_NAME
Zum Ermitteln des ENDPOINTS_SERVICE_NAME haben Sie folgende Möglichkeiten:
Rufen Sie nach der Bereitstellung der Endpoints-Konfiguration die Seite Endpoints in der Cloud Console auf. Die Liste der möglichen ENDPOINTS_SERVICE_NAME wird in der Spalte Dienstname angezeigt.
Bei OpenAPI ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld
host
Ihrer OpenAPI-Spezifikation angegeben haben. Bei gRPC ist der ENDPOINTS_SERVICE_NAME das, was Sie im Feldname
Ihrer gRPC-Endpoints-Konfiguration angegeben haben.
Weitere Informationen zu den gcloud
-Befehlen finden Sie unter gcloud
-Dienste.
Anmeldedaten für den Dienst erstellen
Zur Verwaltung Ihrer API benötigt sowohl ESP als auch ESPv2 die Dienste in der Service Infrastructure. ESP und ESPv2 müssen Zugriffstokens verwenden, um diese Dienste aufzurufen. Wenn Sie ESP oder ESPv2 in Google Cloud-Umgebungen wie GKE oder Compute Engine bereitstellen, ruft der ESP und ESPv2 Zugriffstokens über den Google Cloud-Metadatendienst ab.
Wenn Sie ESP oder ESPv2 in einer anderen Umgebung als Google Cloud bereitstellen, z. B. auf Ihrem lokalen Desktop, einem lokalen Kubernetes-Cluster oder in der Cloud eines anderen Anbieters, müssen Sie eine JSON-Datei für ein Dienstkonto bereitstellen, die einen privaten Schlüssel enthält. ESP und ESPv2 verwenden das Dienstkonto, um Zugriffstokens zu generieren und damit die Dienste aufzurufen, die für die Verwaltung der API erforderlich sind.
Sie können die Google Cloud Console oder die Google Cloud CLI verwenden, um das Dienstkonto und die Datei mit dem privaten Schlüssel zu erstellen:
Console
- Öffnen Sie in der Google Cloud Console die Seite Dienstkonten .
- Klicken Sie auf Auswählen.
- Wählen Sie das Projekt aus, in dem Ihre API erstellt wurde, und klicken Sie auf Öffnen.
- Klicken Sie auf + Dienstkonto erstellen.
- Geben Sie im Feld Name des Dienstkontos den Namen für das Dienstkonto ein.
- Klicken Sie auf Erstellen.
- Klicken Sie auf Weiter.
- Klicken Sie auf Fertig.
- Klicken Sie auf die E-Mail-Adresse des neu erstellten Dienstkontos.
- Klicken Sie auf Schlüssel.
- Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
Klicken Sie auf Erstellen. Daraufhin wird eine JSON-Schlüsseldatei auf Ihren Computer heruntergeladen.
Bewahren Sie die Schlüsseldatei sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden kann. Sie können diese Datei beliebig verschieben und umbenennen.
Klicken Sie auf Schließen.
gcloud
Geben Sie Folgendes ein, um sich die Projekt-IDs für Ihre Google Cloud-Projekte anzeigen zu lassen:
gcloud projects list
Ersetzen Sie im folgenden Befehl PROJECT_ID, damit das Projekt, in dem sich Ihre API befindet, zum Standardprojekt wird:
gcloud config set project PROJECT_ID
Die Google Cloud CLI (
gcloud
) muss berechtigt sein, auf Ihre Daten und Dienste in Google Cloud zuzugreifen:gcloud auth login
Wenn Sie mehrere Konten haben, wählen Sie das Konto aus, das sich im Google Cloud-Projekt mit der API befindet. Wenn Sie
gcloud auth list
ausführen, wird das von Ihnen ausgewählte Konto als aktives Konto für das Projekt angezeigt.Führen Sie zum Erstellen eines Dienstkontos folgenden Befehl aus und ersetzen Sie SERVICE_ACCOUNT_NAME und
My Service Account
durch den zu verwendenden Namen bzw. Anzeigenamen:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
Mit dem Befehl wird dem Dienstkonto eine E-Mail-Adresse im folgenden Format zugewiesen:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Diese E-Mail-Adresse wird für die nachfolgenden Befehle benötigt.
Erstellen Sie eine Dienstkonto-Schlüsseldatei:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Erforderliche IAM-Rollen hinzufügen:
In diesem Abschnitt werden die von ESP und ESPv2 verwendeten IAM-Ressourcen beschrieben, sowie die IAM-Rollen, die das angehängte Dienstkonto benötigt, um auf diese Ressourcen zuzugreifen.
Endpoint-Dienstkonfiguration
ESP und ESPv2 rufen Service Control auf (nutzt die Endpunktdienst-Konfiguration). Die Endpunktdienst-Konfiguration ist eine IAM-Ressource. ESP und ESPv2 benötigen die Rolle Dienstüberwacher, um auf sie zuzugreifen.
Die IAM-Rolle gilt für die Endpunktdienst-Konfiguration, nicht für das Projekt. Ein Projekt kann mehrere Endpunktdienst-Konfigurationen haben.
Verwenden Sie folgenden gcloud-Befehl, um die Rolle dem angehängten Dienstkonto für die Endpunktdienst-Konfiguration hinzuzufügen.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
Dabei ist
* SERVICE_NAME
der Endpunkt-Dienstname
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
das angehängte Dienstkonto.
Cloud Trace
ESP und ESPv2 rufen den
Cloud Trace-Dienst auf, um Trace in ein Projekt zu exportieren. Dieses Projekt wird als Tracing-Projekt bezeichnet. In ESP sind das Tracing-Projekt und das Projekt, zu dem die Endpunktdienstkonfiguration gehört, identisch. In ESPv2 kann das Tracing-Projekt mit dem Flag --tracing_project_id
angegeben werden und entspricht standardmäßig dem Bereitstellungsprojekt.
ESP und ESPv2 benötigen die Rolle Cloud Trace-Agent, um Cloud Trace zu aktivieren.
Verwenden Sie den folgenden gcloud-Befehl, um die Rolle dem angehängten Dienstkonto hinzuzufügen:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
Dabei ist
* TRACING_PROJECT_ID die Tracing-Projekt-ID
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.comdas angehängte Dienstkonto.
Weitere Informationen finden Sie unter
Was sind Rollen und Berechtigungen?
Weitere Informationen zu den Befehlen finden Sie unter gcloud iam service-accounts
.
API-Backend bereitstellen
Sie haben jetzt die Dienstkonfiguration für Service Management, aber noch nicht den Code für das Back-End der API bereitgestellt. In diesem Abschnitt wird die Bereitstellung vorkonfigurierter Container für die Beispiel-API und ESPv2 Beta in Kubernetes beschrieben.
Dienst-Anmeldedaten für ESPv2 bereitstellen
Der ESPv2, der in einem Container ausgeführt wird, benötigt Zugriff auf die lokal in der Datei service-account-creds.json
gespeicherten Anmeldedaten. Damit der ESPv2 Zugriff auf die Anmeldedaten erhält, müssen Sie ein Kubernetes Secret erstellen und als Kubernetes Volume bereitstellen.
So erstellen Sie das Kubernetes Secret und stellen das Volume bereit:
- Falls Sie die Google Cloud Console zum Erstellen des Dienstkontos verwendet haben, benennen Sie die JSON-Datei in
service-account-creds.json
um. Verschieben Sie diese in das Verzeichnis, in dem sich auchapi_descriptor.pb
undapi_config.yaml
befinden. Erstellen Sie mit den Anmeldedaten des Dienstkontos ein Kubernetes Secret:
kubectl create secret generic service-account-creds \ --from-file=service-account-creds.json
Wenn der Vorgang gelingt, wird die folgende Meldung angezeigt:
secret "service-account-creds" created
Die Bereitstellungsmanifestdatei, die zum Bereitstellen der API und des ESPv2 für Kubernetes verwendet wird, enthält bereits das Secret-Volume, wie in den folgenden beiden Abschnitten der Datei gezeigt:
Dienstname konfigurieren und Dienst starten
Der ESP muss den Namen des Diensts kennen, damit er die zuvor mithilfe des Befehls gcloud endpoints services deploy
bereitgestellte Konfiguration ermitteln kann.
So konfigurieren Sie den Dienstnamen und starten den Dienst:
- Speichern Sie eine Kopie der Bereitstellungsmanifestdatei
grpc-bookstore.yaml
im selben Verzeichnis wieservice-account-creds.json
. Öffnen Sie
grpc-bookstore.yaml
und ersetzen Sie SERVICE_NAME durch den Namen Ihres Endpoints-Diensts. Dies ist der Name, den Sie in der Dateiapi_config.yaml
im Feldname
konfiguriert haben.Mit der Option
--rollout_strategy=managed
legen Sie fest, dass der ESPv2 die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option angeben, erkennt der ESPv2 innerhalb einer Minute nach Bereitstellung einer neuen Dienstkonfiguration die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option festzulegen, anstatt eine bestimmte Konfigurations-ID anzugeben, die von ESPv2 verwendet werden soll. Weitere Informationen zu ESPv2-Argumenten finden Sie unter ESPv2-Startoptionen.Starten Sie den Dienst, um ihn auf Kubernetes bereitzustellen:
kubectl create -f grpc-bookstore.yaml
Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:
The connection to the server localhost:8080 was refused - did you specify the right host or port?
Dies weist darauf hin, dass
kubectl
nicht richtig konfiguriert ist. Weitere Informationen finden Sie unterkubectl
konfigurieren.
Externe IP-Adresse des Diensts abrufen
Sie benötigen die externe IP-Adresse des Diensts, um Anfragen an die Beispiel-API senden zu können. Nach dem Start Ihres Diensts im Container kann es einige Minuten dauern, bevor die externe IP-Adresse bereit ist.
Rufen Sie die externe IP-Adresse auf:
kubectl get service
Notieren Sie sich den Wert für
EXTERNAL-IP
und speichern Sie ihn in der Umgebungsvariablen SERVER_IP, die beim Versenden von Anfragen an die Beispiel-API verwendet wird.export SERVER_IP=YOUR_EXTERNAL_IP
Anfrage an die API senden
Zum Senden von Requests an die Beispiel-API können Sie einen gRPC-Beispielclient verwenden, der in Python geschrieben wurde.
Klonen Sie das Git-Repository an dem Ort, an dem der gRPC-Clientcode gehostet wird:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Ändern Sie Ihr Arbeitsverzeichnis:
cd python-docs-samples/endpoints/bookstore-grpc/
Installieren Sie die Abhängigkeiten:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
Senden Sie eine Anfrage an die Beispiel-API:
python bookstore_client.py --host SERVER_IP --port 80
Sehen Sie sich auf der Seite Endpoints > Dienste die Aktivitätsgrafiken für Ihre API an.
Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.
Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.
Wenn Sie als Antwort einen Fehler erhalten haben, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.
Sie haben gerade eine API in Cloud Endpoints bereitgestellt und getestet!
Bereinigen
Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.
Löschen Sie die API:
gcloud endpoints services delete SERVICE_NAME
Ersetzen Sie SERVICE_NAME durch den Namen der API.
Löschen Sie den GKE-Cluster:
gcloud container clusters delete NAME --zone ZONE
Nächste Schritte
- Konfiguration einer eigenen gRPC API für Cloud Endpoints
- DNS konfigurieren:
- Bookstore-Beispiel auf GitHub genauer ansehen; Sowohl der Client als auch der Server sind in Python und Java verfügbar.
- Das Beispiel
getting-started-grpc
ist auf GitHub in den folgenden Sprachen verfügbar: