API-Back-End bereitstellen

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 den ESP konfiguriert, an den ESP übergeben werden. Nur so kann die jeweils aktuelle 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.

Vorbereitung

Sie sollten Folgendes bereits haben:

Bereitstellung vorbereiten

App Engine

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

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:

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 Container 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 Container Registry oder eine andere Registry.
  5. Überprüfen Sie, ob Sie folgende Vorgänge erfolgreich ausführen können:

GKE

Wenn Sie einen Cluster in der Cloud Console 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 Back-End-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

App Engine

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:
    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. Beispiel:

    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 den ESP weitergeleitet. Dieser sendet Anfragen und Antworten zum und vom Container, in dem Ihr Back-End-Servercode ausgeführt wird.

Wenn Sie den 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 sie mit dem Container-Netzwerk 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 den 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. Setzen Sie den Befehl docker run ab, 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 den 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äten 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.

    Zur Seite "Endpoints-Dienste"


    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.

    Loganzeige aufrufen

Weitere Informationen