Erste Schritte mit Cloud Endpoints gRPC für verwaltete Instanzgruppen mit ESPv2

Diese Anleitung zeigt Ihnen, wie Sie einen einfachen Beispiel-gRPC-Dienst mit dem Extensible Service Proxy V2 (ESPv2) in einer verwalteten Instanzgruppe bereitstellen:

In dieser Anleitung wird die Python-Version des bookstore-grpc Stichprobe. gRPC-Beispiele in anderen Sprachen finden Sie unter Weitere Informationen.

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.

  1. Richten Sie ein Google Cloud-Projekt ein und laden Sie die erforderliche Software herunter. Siehe Vorbereitung.
  2. Kopieren und konfigurieren Sie die Dateien aus dem Beispiel bookstore-grpc. Siehe Endpoints konfigurieren.
  3. Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
  4. Stellen Sie die API und ESPv2 im Backend der verwalteten Instanzgruppe (Managed Instance Group) bereit. Siehe API-Backend bereitstellen.
  5. Request an die API senden. Siehe Request an die API senden.
  6. 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. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

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.

Hinweis

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

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Notieren Sie sich die Projekt-ID, da sie später benötigt wird.
  7. Installieren und initialisieren Sie das Google Cloud CLI.
  8. Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten: 
    gcloud components update
  9. Die Google Cloud CLI (gcloud) muss zum Zugriff berechtigt sein Ihre Daten und Dienste in Google Cloud: 
    gcloud auth login
     Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
  10. Legen Sie für das Standardprojekt Ihre Projekt-ID fest: 
    gcloud config set project YOUR_PROJECT_ID

    Ersetzen Sie YOUR_PROJECT_ID durch Ihre Projekt-ID. Wenn Sie weitere Google Cloud-Projekte mit gcloud verwalten möchten, lesen Sie gcloud CLI-Konfigurationen verwalten.

  11. Installieren Sie gRPC und die gRPC-Tools. Informationen dazu finden Sie in der Kurzanleitung für gRPC in Python.

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.

Endpoints konfigurieren

Klonen Sie das Repository zum Beispiel bookstore-grpc aus GitHub.

So konfigurieren Sie Endpoints:

  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. Diese Datei definiert die API für den Bookstore-Dienst.
    2. Erstellen Sie das folgende Verzeichnis: 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: 
      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 gespeicherten bookstore.proto-Datei durchsucht.

  2. Erstellen Sie eine gRPC API-Konfigurationsdatei in YAML:
    1. Speichern Sie eine Kopie der Datei api_config.yaml. Diese Datei definiert die gRPC API-Konfiguration für den Bookstore-Dienst.
    2. 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 in bookstore.proto im Paket endpoints.examples.bookstore definiert. Der vollständig qualifizierte API-Name lautet endpoints.examples.bookstore.Bookstore, genau wie er in der Datei api_config.yaml angezeigt wird.

      apis:
  - name: endpoints.examples.bookstore.Bookstore

Weitere Informationen finden Sie unter 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

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
endpoints.googleapis.com Google Cloud Endpoints

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
gcloud services enable endpoints.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.

API-Back-End bereitstellen

Bisher haben Sie die API-Konfiguration für Service Management, aber noch nicht den Code für das API-Backend bereitgestellt. In diesem Abschnitt erfahren Sie, wie Sie Docker für Ihre verwaltete Instanzgruppe einrichten und den API-Backend-Code sowie den ESPv2 in einem Docker-Container ausführen.

Instanzvorlage erstellen

Erstellen Sie eine Vorlage, um damit eine Gruppe von VM-Instanzen zu erstellen. Jede aus der Vorlage erstellte Instanz startet einen ESPv2 und einen Backend-Anwendungsserver.

  1. Rufen Sie in der Google Cloud Console die Seite Instanzvorlagen auf.

    Zu Instanzvorlagen

  2. Klicken Sie auf Instanzvorlage erstellen.

  3. Geben Sie für Name load-balancing-espv2-template ein.

  4. Legen Sie unter Maschinenkonfiguration den Maschinentyp auf e2-micro fest.

  5. Legen Sie unter Bootlaufwerk das Image auf Container Optimized OS stable version fest.

  6. Wählen Sie unter Firewall die Option HTTP-Traffic zulassen aus.

  7. Klicken Sie auf Verwaltung, Sicherheit, Laufwerke, Netzwerke, Einzelne Mandanten, um die erweiterten Einstellungen einzublenden.

  8. Klicken Sie auf den Tab Verwaltung. Geben Sie unter Automatisierung folgendes Startskript ein: Denken Sie daran, ENDPOINTS_SERVICE_NAME zu aktualisieren.

    sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=bookstore \
  --net=esp_net \
  gcr.io/endpointsv2/python-grpc-bookstore-server:1
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=grpc://bookstore:8000

    Das Skript ruft den Echo-Anwendungsserver und den ESPv2-Proxyserver beim Start der Instanz ab, installiert diese Elemente und startet sie.

  9. Klicken Sie auf Erstellen.

Warten Sie, bis die Vorlage erstellt ist, bevor Sie fortfahren.

Regionale verwaltete Instanzgruppe erstellen

Verwenden Sie zum Ausführen der Anwendung die Instanzvorlage, um eine regionale, verwaltete Instanzgruppe zu erstellen:

  1. Rufen Sie in der Google Cloud Console die Seite Instanzgruppen auf.

    Zu den Instanzgruppen

  2. Klicken Sie auf Instanzgruppe erstellen.

  3. Geben Sie für Name load-balancing-espv2-group ein.

  4. Wählen Sie unter Standort die Option Mehrere Zonen aus.

  5. Wählen Sie unter Region die Option us-central1 aus.

  6. Klicken Sie auf das Drop-down-Menü Zonen konfigurieren, um Zonen einzublenden. Wählen Sie die folgenden Zonen aus:

    • us-central1-b
    • us-central1-c
    • us-central1-f

  7. Wählen Sie unter Instanzvorlage load-balancing-espv2-template aus.

  8. Wählen Sie unter Autoscaling die Option Kein Autoscaling aus.

  9. Legen Sie Anzahl der Instanzen auf 3 fest.

  10. Wählen Sie unter Weiterverteilung von Instanzen die Option Ein aus.

  11. Wählen Sie unter Automatische Reparatur und Systemdiagnose die Option Keine Systemdiagnose aus.

  12. Klicken Sie auf Erstellen. Damit kehren Sie wieder zur Seite Instanzgruppen zurück.

Load-Balancer erstellen

Dieser Abschnitt erläutert die Schritte zum Erstellen eines regionalen Load-Balancers, der TCP-Traffic an die Instanzgruppe weiterleitet.

  1. Rufen Sie in der Google Cloud Console die Seite Load-Balancer erstellen auf.

    Zur Seite „Load-Balancer erstellen”

  2. Klicken Sie unter TCP-Load-Balancing auf Konfiguration starten.

  3. Wählen Sie unter Internet oder nur intern die Option Vom Internet zu meinen VMs aus.

  4. Wählen Sie unter Mehrere Regionen oder einzelne Region die Option Nur eine Region aus.

  5. Wählen Sie unter Backend-Typ die Option Backend-Dienst.

  6. Klicken Sie auf Weiter.

  7. Geben Sie für Name espv2-load-balancer ein.

  8. Wählen Sie unter Backend-Konfiguration die Region us-central1.

  9. Wählen Sie die Instanzgruppe load-balancing-espv2-group aus.

  10. Erstellen Sie unter Systemdiagnose eine neue Systemdiagnose.

    • Geben Sie im Feld des Namens espv2-load-balancer-check ein.
    • Prüfen Sie, ob das Protokoll TCP und der Port 80 ist.

  11. Geben Sie unter Frontend-Konfiguration die Portnummer 80 ein.

  12. Prüfen Sie unter Prüfen und finalisieren, ob:

    • Die Instanzgruppe ist load-balancing-espv2-group.
    • Die Region us-central1 ist.
    • Das Protokoll TCP ist.
    • Der IP:Port EPHEMERAL:80 ist.

  13. Suchen Sie nach der Erstellung des Load-Balancers auf der Seite Load-Balancer die IP-Adresse.

    Load-Balancer aufrufen

Anfrage an die API senden

Wenn Sie die Anfrage von derselben Instanz aus senden, in der die Docker-Container ausgeführt werden, können Sie SERVER_IP durch localhost ersetzen. Andernfalls ersetzen Sie SERVER_IP durch die externe IP-Adresse der Instanz.

Sie finden die externe IP-Adresse, wenn Sie folgenden Befehl ausführen:

gcloud compute instances list

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: 

    pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt

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

      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!

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.

  1. Die gcloud CLI (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste in Google Cloud zuzugreifen:

    gcloud auth login

  2. Geben Sie Folgendes ein, um sich die Projekt-IDs für Ihre Google Cloud-Projekte anzeigen zu lassen:

    gcloud projects list

  3. Verwenden Sie die entsprechende Projekt-ID aus dem vorherigen Schritt, um das Google Cloud-Standardprojekt auf das Projekt festzulegen, in dem sich Ihre Anwendung befindet:

    gcloud config set project [YOUR_PROJECT_ID]

  4. Ermitteln Sie den Namen aller verwalteten Dienste in Ihrem Google Cloud-Projekt:

    gcloud endpoints services list

  5. Löschen Sie den Dienst aus Service Management. Ersetzen Sie dabei SERVICE_NAME durch den Namen des Dienstes, den Sie entfernen möchten:

    gcloud endpoints services delete SERVICE_NAME

    Der verwaltete Dienst wird bei Ausführung von gcloud endpoints services delete nicht sofort gelöscht. Service Management deaktiviert den verwalteten Dienst 30 Tage lang, sodass Sie ihn bei Bedarf wiederherstellen können. Nach 30 Tagen löscht Service Management den verwalteten Dienst endgültig.

  6. Rufen Sie die Seite Load-Balancer auf.

    Load-Balancer aufrufen

    Löschen Sie den Load-Balancer espv2-load-balancer mit der Systemdiagnose espv2-load-balancer-check.

  7. Gehen Sie zu der Seite Instanzgruppen.

    Zu den Instanzgruppen

    load-balancing-espv2-group löschen

  8. Gehen Sie zur Seite Instanzvorlage.

    Instanzvorlagen aufrufen

    load-balancing-espv2-template löschen.

Nächste Schritte