API-Back-End bereitstellen

OpenAPI | gRPC

Auf dieser Seite wird erläutert, wie Sie den Back-End-Code der API und den Extensible Service Proxy (ESP) in Google Kubernetes Engine, Compute Engine und der flexiblen App Engine-Umgebung bereitstellen.

Der genaue Ablauf der Bereitstellung hängt von der Plattform ab, auf der die API gehostet wird. Auf jeden Fall müssen in einem Schritt der Dienstname und eine Option, die ESP konfiguriert, an ESP übergeben werden. Nur so kann die aktuellste Cloud Endpoints-Dienstkonfiguration verwendet werden. Anhand dieser Informationen kann ESP die Endpoints-Konfiguration der API abrufen und Anfragen und Antworten weiterleiten, damit Endpoints die API verwalten kann.

Hinweis :ESP und ESPV2 unterstützen jeweils unterschiedliche Umgebungen. ESP wird nur in der flexiblen App Engine-Umgebung unterstützt und ist nicht in der App Engine-Standardumgebung verfügbar. Im Gegensatz dazu kann ESPV2 in GKE und Kubernetes bereitgestellt werden, unterstützt aber App Engine nicht.

Vorbereitung

Sie sollten Folgendes bereits haben:

• Sie haben ein Google Cloud Projekt erstellt.
• Konfigurierte Endpoints
• Eine bereitgestellte Endpoints-Konfiguration

Bereitstellung vorbereiten

Flexible App Engine-Umgebung

Abgesehen von einem kurzen zusätzlichen Konfigurationsschritt (nachfolgend beschrieben) erfolgt die Bereitstellung der API für die Verwaltung durch Endpoints genau wie die Bereitstellung einer anderen Anwendung in der flexiblen App Engine-Umgebung. In der App Engine-Dokumentation wird beschrieben, wie Sie:

• Konfigurationsdateien organisieren
• die Konfigurationsdatei app.yaml erstellen
• app.yaml-Dateien für einzelne Dienste konfigurieren, wenn Ihre Anwendung auf Mikrodiensten basiert (siehe Mehrere Dienstanwendungen bereitstellen)

Zur Bereitstellung der API in App Engine setzen Sie den Befehl gcloud app deploy ab. Dadurch wird mithilfe des Dienstes Container Builder automatisch ein Container-Image erstellt. Dieses Image wird anschließend in der flexiblen App Engine-Umgebung bereitgestellt.

Vor der Bereitstellung:

• Der Inhaber des Google Cloud Projekts muss die App Engine-Anwendung erstellen.
• Ihr Nutzerkonto muss die erforderlichen Berechtigungen enthalten.

Compute Engine

Damit Endpoints die API verwalten kann, müssen Sie den ESP sowie den Back-End-Servercode für die API installieren und konfigurieren. Sie müssen Docker auf Ihrer Compute Engine-VM-Instanz installieren, damit Sie das ESP-Docker-Image ausführen können, das über Artifact Registry kostenlos verfügbar ist.

Vor der Bereitstellung:

Im Folgenden werden die allgemeinen Schritte beschrieben, die erforderlich sind, bevor Sie die API und ESP in Compute Engine bereitstellen können. Grundsätzlich gehen Sie dabei genauso vor wie beim Ausführen des Back-End-Servercodes in Compute Engine.

1. Erstellen, konfigurieren und starten Sie Ihre VM-Instanz. Entsprechende Informationen finden Sie in der Compute Engine-Dokumentation.
2. Installieren Sie Docker Enterprise Edition (EE) oder Docker Community Edition (CE) auf der VM-Instanz. Siehe Docker installieren.
3. Erstellen Sie einen Docker-Container für den Back-End-Servercode. Siehe Cloud-Build-Dokumentation.
4. Verschieben Sie den Container in die Artifact Registry oder eine andere Registry.
5. Überprüfen Sie, ob Sie folgende Vorgänge erfolgreich ausführen können:
   • eine Verbindung zur VM-Instanz herstellen,
   • das Docker-Image ausführen können, um den Back-End-Server auf der VM-Instanz zu starten (siehe Referenz zur Docker-Ausführung), und
   • Anfragen an die API senden können.

GKE

Wenn Sie einen Cluster in der Google Cloud -Konsole erstellen, enthalten die OAuth-Bereiche, die dem Dienstkonto des Clusters gewährt werden, standardmäßig die von Endpoints benötigten Bereiche:

• Service Control: Aktiviert
• Service Management: Schreibgeschützt

Wenn Sie einen Cluster mit dem Befehl gcloud container clusters create oder mithilfe einer Konfigurationsdatei eines Drittanbieters erstellen, vergessen Sie nicht, die folgenden Bereiche anzugeben:

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

Weitere Informationen finden Sie unter Was sind Zugriffsbereiche?.

Vor der Bereitstellung:

Wenn Sie die Manifestdatei der Bereitstellung um einen kleinen Abschnitt erweitern, können Sie das ESP-Docker-Image neben der containerisierten Anwendung auf Ihren Containerclustern ausführen. Im Folgenden wird beschrieben, welche allgemeinen Schritte erforderlich sind, bevor Sie Ihre API mit dem ESP in GKE bereitstellen können. Grundsätzlich gehen Sie dabei genauso vor wie beim Ausführen des Backend-Servercodes in GKE.

1. Stellen Sie die containerisierte Anwendung auf den Containerclustern bereit. In der GKE-Dokumentation werden folgende Schritte beschrieben:
   1. Anwendung in einem Docker-Image verpacken
   2. Image in eine Registry hochladen
   3. Container-Cluster erstellen
   4. Anwendung auf dem Cluster bereitstellen
   5. Anwendung im Internet freigeben
2. Überprüfen Sie, ob Sie folgende Vorgänge erfolgreich ausführen können:
   • API-Server starten
   • Anfragen an die API senden können.

API und ESP bereitstellen

Flexible App Engine-Umgebung

So stellen Sie die API und den ESP in App Engine bereit:

1. Rufen Sie den Dienstnamen Ihrer API ab. Das ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments angegeben haben.
2. Bearbeiten Sie die app.yaml-Datei und fügen Sie einen Abschnitt namens endpoints_api_service ein, der den Dienstnamen enthält. Sie können die app.yaml-Datei aus der Anleitung als Modell verwenden:
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ersetzen Sie ENDPOINTS-SERVICE-NAME durch den Dienstnamen der API.

   Fügen Sie die Laufzeit- und Umgebungsvariablen in die Konfigurationsdatei app.yaml ein.

   Beispiel:

   runtime: nodejs
   env: flex
   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   Mit der Option rollout_strategy: managed legen Sie fest, dass der ESP die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll.

   Wenn Ihre Anwendung auf Mikrodiensten basiert, müssen Sie in jeder app.yaml-Datei den Abschnitt endpoints_api_service einfügen.

3. Speichern Sie die app.yaml-Datei (bzw. -Dateien).
4. Stellen Sie den Back-End-Code und den ESP in App Engine bereit:

   gcloud app deploy

Da Sie den Abschnitt endpoints_api_service in die Datei app.yaml eingefügt haben, wird der ESP durch den Befehl gcloud app deploy in einem separaten Container in der flexiblen App Engine-Umgebung bereitgestellt und konfiguriert. Sämtliche Anfragen werden über ESP weitergeleitet. Dieser sendet Anfragen und Antworten zum und vom Container, in dem Ihr Back-End-Servercode ausgeführt wird.

Wenn Sie ESP für die Verwendung einer bestimmten Konfigurations-ID konfigurieren müssen:

1. Fügen Sie im Abschnitt endpoints_api_service der Datei app.yaml das Feld config_id ein und legen Sie dafür eine bestimmte Konfigurations-ID fest.
2. Entfernen Sie entweder rollout_strategy: managed oder legen Sie rollout_strategy auf fixed fest. Die Option fixed konfiguriert den ESP so, dass die in config_id angegebene Dienstkonfiguration verwendet wird.
3. Stellen Sie die API und den ESP wieder bereit: gcloud app deploy

Es wird empfohlen, den ESP nicht für lange Zeit so zu konfigurieren, dass er eine bestimmte Konfigurations-ID verwendet. Andernfalls müssen Sie ihn nämlich nach jedem Bereitstellen einer aktualisierten Dienstkonfiguration neu starten, damit er sie verwendet.

So entfernen Sie eine bestimmte Konfigurations-ID:

1. Entfernen Sie die Option config_id aus der Datei app.yaml.
2. Fügen Sie die Option rollout_strategy: managed ein.
3. Setzen Sie den Befehl gcloud app deploy ab.

Wenn Sie die Option rollout_strategy: managed verwenden, nehmen Sie config_id: YOUR_SERVICE_CONFIG_ID nicht in die Datei app.yaml auf. Andernfalls schlägt gcloud app deploy mit folgendem Fehler fehl:

config_id is forbidden when rollout_strategy is set to "managed".

Bei der erstmaligen Bereitstellung der API in der flexiblen App Engine-Umgebung kann es durch die Einrichtung der virtuellen Maschine (VM) und sonstiger Infrastruktur zu einer Verzögerung kommen. Weitere Informationen finden Sie unter Erfolgreiche Bereitstellung gewährleisten in der App Engine-Dokumentation.

Compute Engine

So stellen Sie die API und den ESP in Compute Engine mit Docker bereit:

1. Stellen Sie eine Verbindung zur VM-Instanz her. Ersetzen Sie INSTANCE_NAME durch den Namen der VM-Instanz:

   gcloud compute ssh INSTANCE_NAME

2. Erstellen Sie Ihr eigenes Container-Netzwerk namens esp_net.

   sudo docker network create --driver bridge esp_net

3. Führen Sie eine Image-Instanz des Back-End-Servercodes aus und verbinden Sie diese mit dem Containernetzwerk esp_net:

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • Ersetzen Sie YOUR_API_CONTAINER_NAME durch den Namen des Containers.
   • Ersetzen Sie YOUR_PROJECT_ID durch die Google Cloud Projekt-ID, die Sie beim Hochladen des Images verwendet haben.
   • Ersetzen Sie YOUR_IMAGE durch den Namen des Images.
4. Rufen Sie den Dienstnamen Ihrer API ab. Das ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments angegeben haben.
5. Führen Sie eine Instanz des ESP-Docker-Images aus:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • Ersetzen Sie SERVICE_NAME durch den Namen des Dienstes.
   • Ersetzen Sie YOUR_API_CONTAINER_NAME durch den Namen des API-Containers.

   Mit der Option --rollout_strategy=managed legen Sie fest, dass der ESP die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll.

Wenn Sie ESP für die Verwendung einer bestimmten Konfigurations-ID konfigurieren müssen:

1. Fügen Sie die Option --version ein und legen Sie dafür eine bestimmte Konfigurations-ID fest.
2. Entfernen Sie entweder die Option --rollout_strategy=managed oder setzen Sie --rollout_strategy auf fixed. Die Option fixed konfiguriert den ESP so, dass die in --version angegebene Dienstkonfiguration verwendet wird.
3. Setzen Sie den Befehl docker run noch einmal ab.

Wenn Sie sowohl die Option --rollout_strategy=managed als auch --version angeben, startet der ESP mit der von Ihnen unter --version angegebenen Konfiguration, wird jedoch im verwalteten Modus ausgeführt und ruft die aktuellste Konfiguration ab.

Es wird empfohlen, den ESP nicht für lange Zeit so zu konfigurieren, dass er eine bestimmte Konfigurations-ID verwendet. Andernfalls müssen Sie ihn nämlich nach jedem Bereitstellen einer aktualisierten Dienstkonfiguration neu starten, damit er sie verwendet.

So entfernen Sie eine bestimmte Konfigurations-ID:

1. Entfernen Sie die Option --version in den ESP-Flags für docker run.
2. Fügen Sie die Option --rollout_strategy=managed ein.
3. Geben Sie den Befehl docker run aus, um den ESP neu zu starten.

Eine vollständige Liste der Optionen für den ESP-Start finden Sie unter ESP-Startoptionen.

GKE

So stellen Sie den ESP für GKE bereit:

1. Rufen Sie den Dienstnamen der API ab. Das ist der Name, den Sie im Feld host des OpenAPI-Dokuments konfiguriert haben.
2. Öffnen Sie die Manifestdatei der Bereitstellung (deployment.yaml) und fügen Sie den folgenden Code in den Container-Abschnitt ein:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed"
     ]

   Ersetzen Sie SERVICE_NAME durch den Dienstnamen der API.

   Mit der Option --rollout_strategy=managed" legen Sie fest, dass der ESP die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll.

3. Starten Sie den Kubernetes-Dienst mit dem Befehl kubectl create:

   kubectl create -f deployment.yaml

Wenn Sie ESP für die Verwendung einer bestimmten Konfigurations-ID konfigurieren müssen:

1. Fügen Sie die Option --version in die Manifestdatei der Bereitstellung ein und legen Sie dafür eine bestimmte Konfigurations-ID fest.
2. Entfernen Sie entweder --rollout_strategy=managed oder legen Sie --rollout_strategy auf fixed fest. Die Option fixed konfiguriert den ESP so, dass die in --version angegebene Dienstkonfiguration verwendet wird.
3. Starten Sie den Kubernetes-Dienst: kubectl create -f deployment.yaml

Wenn Sie sowohl die Option --rollout_strategy=managed als auch --version angeben, startet der ESP mit der von Ihnen unter --version angegebenen Konfiguration, wird jedoch im verwalteten Modus ausgeführt und ruft die neueste Konfiguration ab.

Es wird empfohlen, den ESP nicht für lange Zeit so zu konfigurieren, dass er eine bestimmte Konfigurations-ID verwendet. Andernfalls müssen Sie ihn nämlich nach jedem Bereitstellen einer aktualisierten Dienstkonfiguration neu starten, damit er diese verwendet.

So entfernen Sie eine bestimmte Konfigurations-ID:

1. Entfernen Sie die Option --version aus der Manifestdatei der Bereitstellung.
2. Fügen Sie --rollout_strategy=managed ein.
3. Starten Sie den Kubernetes-Dienst: kubectl create -f deployment.yaml

Eine vollständige Liste der Optionen für den ESP-Start finden Sie unter ESP-Startoptionen.

API-Aktivität verfolgen

Nach der Bereitstellung des ESP und des API-Back-Ends können Sie mit Tools wie etwa curl oder Postman Anfragen an die API senden. Wenn Sie als Antwort einen Fehler erhalten haben, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.

Nachdem einige Anfragen gesendet wurden, haben Sie folgende Optionen:

• Wechseln Sie zu Endpoints > Dienste, um die Aktivitätsdiagramme für die API anzusehen.
  

  Endpoints-Dienste aufrufen

  
  Es kann einige Momente dauern, bis die Anfrage in den Grafiken angezeigt wird.

• Sehen Sie sich die Anfragelogs für Ihre API auf der Cloud Logging-Seite an.
  

  Zur Seite „Log-Explorer“

Nächste Schritte

• Fehlerbehebung bei der flexiblen App Engine-Bereitstellung
• Fehlerbehebung bei Cloud Endpoints auf Compute Engine
• Fehlerbehebung bei Cloud Endpoints in Google Kubernetes Engine