Cloud Endpoints gRPC für Cloud Run mit ESPv2 einrichten

Cloud Run-Hostname reservieren

Sie müssen einen Cloud Run-Hostnamen für den ESPv2-Dienst reservieren, um das OpenAPI-Dokument oder die gRPC-Dienstkonfiguration zu konfigurieren. Zur Reservierung eines Hostnamens stellen Sie einen Beispielcontainer für Cloud Run bereit. Später führen Sie eine Bereitstellung des ESPv2-Containers für den gleichen Cloud Run-Dienst aus.

1. Achten Sie darauf, dass die gcloud CLI zum Zugriff auf Ihre Daten und Dienste berechtigt ist.
   1. Melden Sie sich an.

      gcloud auth login

   2. Es wird ein neuer Browsertab geöffnet. Dort wählen Sie ein Konto aus, das für das Google Cloud-Projekt, das Sie zum Bereitstellen von ESPv2 für Cloud Run erstellt haben, die Rolle Bearbeiter oder Inhaber hat.
2. Legen Sie die Region fest.

   gcloud config set run/region us-central1

3. Stellen Sie das Beispiel-Image gcr.io/cloudrun/hello für Cloud Run bereit. Ersetzen Sie CLOUD_RUN_SERVICE_NAME durch den Namen, den Sie für den Dienst verwenden möchten.

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   Bei erfolgreicher Befehlsausführung wird eine Meldung angezeigt, die in etwa so aussieht:

   Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   Hier ein Beispiel, in dem CLOUD_RUN_SERVICE_NAME auf gateway festgelegt ist:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   In diesem Beispiel ist https://gateway-12345-uc.a.run.app die CLOUD_RUN_SERVICE_URL und gateway-12345-uc.a.run.app der CLOUD_RUN_HOSTNAME.

4. Notieren Sie sich CLOUD_RUN_SERVICE_NAME und CLOUD_RUN_HOSTNAME. Später stellen Sie ESPv2 für den Cloud Run-Dienst CLOUD_RUN_SERVICE_NAME bereit. Sie geben CLOUD_RUN_HOSTNAME im Feld host Ihres OpenAPI-Dokuments an.

Endpoints konfigurieren

Das Beispiel bookstore-grpc enthält die Dateien, die Sie lokal kopieren und konfigurieren müssen.

1. Erstellen Sie aus der Datei .proto Ihres Dienstes eine abgeschlossene protobuf-Deskriptordatei:
   1. Speichern Sie eine Kopie von bookstore.proto aus dem Beispiel-Repository in Ihrem aktuellen Arbeitsverzeichnis. Diese Datei definiert die API für den Bookstore-Dienst.
   2. Erstellen Sie das folgende Verzeichnis unter Ihrem Arbeitsverzeichnis: mkdir generated_pb2
   3. Erstellen Sie die Deskriptordatei api_descriptor.pb mit dem Protokollpuffercompiler protoc. Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem Sie bookstore.proto gespeichert haben:

      python3 -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 gespeicherten bookstore.proto-Datei durchsucht.

2. Erstellen Sie eine Textdatei mit dem Namen api_config.yaml in Ihrem aktuellen Arbeitsverzeichnis (dasselbe Verzeichnis, das bookstore.proto enthält). Der Einfachheit halber bezieht sich diese Seite auf das gRPC API-Konfigurationsdokument mit diesem Dateinamen, Sie können es aber auch anders benennen, wenn Sie möchten. Fügen Sie der Datei diesen Inhalt hinzu:

   # The configuration schema is defined by the service.proto file.
   # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
   
   type: google.api.Service
   config_version: 3
   name: CLOUD_RUN_HOSTNAME
   title: Cloud Endpoints + Cloud Run gRPC
   apis:
     - name: endpoints.examples.bookstore.Bookstore
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true
   backend:
     rules:
       - selector: "*"
         address: grpcs://BACKEND_HOST_NAME
   

   Die Einrückung ist für das YAML-Format wichtig. Das Feld name muss beispielsweise auf derselben Ebene wie type sein.

3. Legen Sie im Feld name den Wert CLOUD_RUN_HOSTNAME fest. Dies ist der Hostname in der URL, der oben unter Cloud Run-Hostname reservieren reserviert wurde. Lassen Sie dabei die Protokollkennung wie https:// oder grpcs:// weg.

4. Ersetzen Sie im Abschnitt backend.rules im Feld address BACKEND_HOST_NAME durch den tatsächlichen Cloud Run-Dienst von gRPC Bookstore, der unter Vorbereitung erstellt wurde.

5. Beachten Sie den Wert des Attributs title in der Datei api_config.yaml:

   title: Cloud Endpoints + Cloud Run gRPC

   Der Wert des Attributs title wird nach Bereitstellung der Konfiguration zum Namen des Endpoints-Dienstes.

6. Speichern Sie Ihr gRPC API-Konfigurationsdokument.

Weitere Informationen finden Sie unter Cloud Endpoints konfigurieren.

Endpoints-Konfiguration bereitstellen

Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy bereitgestellt. Dieser Befehl erstellt mithilfe von Service Management einen verwalteten Dienst.

1. Sie müssen sich in dem Verzeichnis befinden, in dem die Dateien api_descriptor.pb und api_config.yaml liegen.
2. 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
   

3. 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 und bookstore.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.

Erforderliche Dienste prüfen

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 Feld name Ihrer gRPC-Endpoints-Konfiguration angegeben haben.

Weitere Informationen zu den gcloud-Befehlen finden Sie unter gcloud-Dienste.

Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Cloud Endpoints-Konfigurationsbereitstellung.

Weitere Informationen finden Sie unter Endpoints-Konfiguration bereitstellen.

Neues ESPv2-Image erstellen

Erstellen Sie die Endpoints-Dienstkonfiguration in einem neuen Docker-Image für ESPv2. Später werden Sie dieses Image für den reservierten Cloud Run-Dienst bereitstellen.

So integrieren Sie die Dienstkonfiguration in ein neues ESPv2-Docker-Image:

1. Laden Sie dieses Skript auf Ihren lokalen Computer herunter, auf dem die gcloud CLI installiert ist.

2. Führen Sie das Skript mit dem folgenden Befehl aus:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   Geben Sie unter CLOUD_RUN_HOSTNAME den Hostnamen der URL ein, den Sie oben unter Cloud Run-Hostname reservieren reserviert haben. Lassen Sie dabei die Protokollkennung https:// weg.

   Beispiel:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. Das Skript verwendet den gcloud-Befehl, um die Dienstkonfiguration herunterzuladen, die Dienstkonfiguration in ein neues ESPv2-Image einzubinden und das neue Image in Ihre Projekt-Container Registry hochzuladen. Das Skript verwendet automatisch den neuesten Release von ESPv2, der durch ESP_VERSION im Ausgabe-Image-Namen angegeben ist. Das Ausgabebild wird hochgeladen in:

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

   Beispiel:

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

ESPv2-Container bereitstellen

1. Stellen Sie den Cloud Run-Dienst von ESPv2 mit dem neuen Image bereit, das Sie oben erstellt haben. Ersetzen Sie dabei CLOUD_RUN_SERVICE_NAME durch den Cloud Run-Dienstnamen, den Sie bei der ursprünglichen Reservierung des Hostnamens im Abschnitt Cloud Run-Hostname reservieren verwendet haben:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESP_PROJECT_ID

2. Wenn Sie Endpoints so konfigurieren möchten, dass zusätzliche ESPv2-Startoptionen wie das Aktivieren von CORS verwendet werden, können Sie die Argumente in der Umgebungsvariablen ESPv2_ARGS übergeben:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESP_PROJECT_ID

   Weitere Informationen und Beispiele zum Festlegen der Umgebungsvariablen ESPv2_ARGS, einschließlich der Liste der verfügbaren Optionen und Informationen zur Angabe mehrerer Optionen, finden Sie unter Flags in Extensible Service Proxy V2.

3. Erteilen Sie ESPv2 die Berechtigung zum Aufrufen Ihrer Cloud Run-Dienste. Führen Sie für jeden Dienst den folgenden Befehl aus. Geben Sie folgenden Befehl ein:
   • Ersetzen Sie BACKEND_SERVICE_NAME durch den Namen des aufzurufenden Cloud Run-Dienstes. Wenn Sie den Dienst verwenden, der durch die Bereitstellung von "gcr.io/endpointsv2/python-grpc-bookstore-server:2" erstellt wurde, verwenden Sie python-grpc-bookstore-server als diesen Wert.
   • Ersetzen Sie ESP_PROJECT_NUMBER durch die Projektnummer des Projekts, das Sie für ESPv2 erstellt haben. Sie finden sie zum Beispiel auf der Seite IAM in der Google Cloud Console und unter Standardmäßiges Compute-Dienstkonto. Dies ist das Dienstkonto, das im Member-Flag verwendet wird.

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

Weitere Informationen finden Sie unter Zugriff mit IAM verwalten.

Anfragen an die API senden

Zum Senden von Requests an die Beispiel-API können Sie einen gRPC-Beispielclient verwenden, der in Python geschrieben wurde.

1. 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

2. Ändern Sie Ihr Arbeitsverzeichnis:

   cd python-docs-samples/endpoints/bookstore-grpc/

3. Installieren Sie die Abhängigkeiten:

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

4. Senden Sie eine Anfrage an die Beispiel-API:

   python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

   Geben Sie den Hostnamen Ihres ESPv2-Cloud Run-Dienstes in CLOUD_RUN_HOSTNAME ohne die Protokollkennung an. Beispiel:

   python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

   • Sehen Sie sich auf der Seite Endpoints > Dienste die Aktivitätsgrafiken für Ihre API an.

     Endpoints-Dienste aufrufen

     Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.

   • Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.

     Zur Seite „Log-Explorer“

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!

API-Aktivität verfolgen

1. Sehen Sie sich in der Google Cloud Console auf der Seite Endpoints > Dienste die Aktivitätsgrafiken Ihrer API an.

   Endpoints-Aktivitätsgrafiken ansehen

   Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.

2. Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.

   Endpoints-Anfragelogs ansehen

Entwicklerportal für die API erstellen

Sie können das Cloud Endpoints-Portal verwenden, um ein Entwicklerportal zu erstellen. Dabei handelt es sich um eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.