Extensible Service Proxy lokal oder auf einer anderen Plattform ausführen

OpenAPI | gRPC

Auf dieser Seite wird erläutert, wie Sie eine Instanz von Extensible Service Proxy (ESP) auf einem lokalen Rechner, mit einem anderen Cloud-Anbieter wie Amazon Web Services (AWS) oder in einem Kubernetes-Cluster, der sich nicht in der Google Cloud befindet, konfigurieren und ausführen.

Sie können ESP auf einem Linux- oder macOS-Computer oder einer virtuellen Maschine (VM) ausführen. Microsoft Windows wird nicht unterstützt. Sie können die Anwendung und ESP auf demselben Host oder auf verschiedenen Hosts bereitstellen. Das Hosting einer lokalen Instanz von ESP ermöglicht Folgendes:

• ESP vor der Bereitstellung auf einer Produktionsplattform testen
• Überprüfen, ob die Sicherheitseinstellungen konfiguriert sind und ordnungsgemäß funktionieren und ob Messwerte und Logs auf der Seite Endpoints > Dienste wie erwartet angezeigt werden

Hinweis: Es empfiehlt sich, für die Entwicklung und die Produktion unterschiedliche Google Cloud-Projekte zu verwenden. Diese Einrichtung vermeidet das Mischen von Logs und Messwerten für Produktion und Entwicklung.

Hinweis: Extensible Service Proxy V2 (ESPv2) unterstützt alle unten beschriebenen Features.

Vorbereitung

Als Ausgangspunkt geht diese Seite von Folgendem aus:

• Sie haben Docker installiert, falls Sie den ESP-Container lokal oder auf einer VM bereitstellen. Weitere Informationen finden Sie unter Docker installieren.

• Sie haben eine API lokal oder auf einem Host bereitgestellt, der für den Host erreichbar ist, auf dem ESP ausgeführt wird.

• Sie haben Cloud Endpoints konfiguriert und die Konfiguration bereitgestellt, um für Ihre API einen verwalteten Dienst zu erstellen.

Wenn Sie eine API zum Testen mit ESP benötigen, können Sie den Beispielcode im Abschnitt Optional: Beispiel-API verwenden konfigurieren und bereitstellen. Falls Sie Ihre API bereits konfiguriert und bereitgestellt haben, fahren Sie mit Dienstkonto erstellen fort.

Optional: Beispiel-API verwenden

In diesem Abschnitt werden Sie Schritt für Schritt durch die Konfiguration und lokale Bereitstellung des Beispiels getting-started für Endpoints geführt. Führen Sie die Schritte in diesem Abschnitt nur aus, wenn Sie keine API zum Testen mit ESP haben.

Das Cloud Endpoints-Beispiel getting-started ist in verschiedenen Sprachen verfügbar. Die Seite Beispiele enthält Links zum GitHub-Speicherort des Beispiels getting-started in Ihrer bevorzugten Sprache. Folgen Sie der Anleitung in der Datei README.md des Beispiels für die lokale Ausführung und befolgen Sie dann die Anleitung in diesem Abschnitt, um Endpoints zu konfigurieren und die Endpoints-Konfiguration bereitzustellen.

Erforderliche Software abrufen

Wenn Sie noch keine Python-Entwicklungsumgebung eingerichtet haben, lesen Sie die Anleitung unter Python-Entwicklungsumgebung einrichten. Prüfen Sie, ob Folgendes installiert ist:

• virtualenv
• Google Cloud CLI
• curl

Beispielcode abrufen

1. Klonen Sie das Repository der Beispielanwendung auf Ihren lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd python-docs-samples/endpoints/getting-started
   

Endpoints konfigurieren

1. Öffnen Sie im Verzeichnis mit dem Beispielcode die Konfigurationsdatei openapi.yaml.

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

2. Ersetzen Sie im Feld host YOUR-PROJECT-ID durch Ihre Google Cloud-Projekt-ID.

   Wichtig: Dies muss dasselbe Projekt sein, das Sie unter Dienstkonto erstellen ausgewählt haben.

3. Speichern Sie die Datei openapi.yaml.

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. gcloud CLI aktualisieren

   gcloud components update

2. Prüfen Sie, ob die gcloud CLI (gcloud) berechtigt ist, auf Ihre Daten und Dienste in Google Cloud zuzugreifen:

   gcloud auth login

   Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.

3. Legen Sie für das Standardprojekt Ihre Projekt-ID fest:

   gcloud config set project YOUR-PROJECT-ID
   

   Ersetzen Sie YOUR-PROJECT-ID durch die Projekt-ID des Google Cloud-Projekts, das Sie in der Datei openapi.yaml angegeben haben.

4. Stellen Sie Ihre Konfiguration bereit:

   gcloud endpoints services deploy openapi.yaml

In der Service Management API wird auf der Grundlage des Textes, den Sie im Feld host der Datei openapi.yaml angegeben haben, ein neuer Endpoints-Dienst mit dem Namen echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog erstellt (falls noch nicht vorhanden) und der Dienst dann entsprechend Ihrer OpenAPI-Konfigurationsdatei konfiguriert.

Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Warnhinweise, die besagen, dass für die Pfade in der Datei openapi.yaml kein API-Schlüssel erforderlich ist, können Sie ignorieren. Nach erfolgreichem Abschluss des Vorgangs wird eine Zeile wie die folgende angezeigt, die die Dienstkonfigurations-ID und den Dienstnamen in eckigen Klammern enthält:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Im obigen Beispiel ist 2017-02-13r0 die Dienstkonfigurations-ID und echo-api.endpoints.example-project-12345.cloud.goog der Dienstname.

Lokalen Server starten

1. Erstellen Sie eine virtualenv, aktivieren Sie sie und installieren Sie die Anwendungsabhängigkeiten:

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

2. Starten Sie den Server:

   python main.py
   

3. Öffnen Sie ein anderes Terminalfenster und verwenden Sie curlcurl zum Senden einer Anfrage:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8080/echo
   

   Die API gibt die von Ihnen gesendete Meldung zurück und antwortet mit folgender Zeile:

   {
   "message": "hello world"
   }

Dienstkonto 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 entweder die Google Cloud Console oder die Google Cloud CLI verwenden um das Dienstkonto und die Datei mit dem privaten Schlüssel zu erstellen:

Console

1. Öffnen Sie in der Google Cloud Console die Seite Dienstkonten.

   Zur Seite „Dienstkonten“

2. Klicken Sie auf Auswählen.
3. Wählen Sie das Projekt aus, in dem Ihre API erstellt wurde, und klicken Sie auf Öffnen.
4. Klicken Sie auf + Dienstkonto erstellen.
5. Geben Sie im Feld Name des Dienstkontos den Namen für das Dienstkonto ein.
6. Klicken Sie auf Erstellen.
7. Klicken Sie auf Weiter.
8. Klicken Sie auf Fertig.
9. Klicken Sie auf die E-Mail-Adresse des neu erstellten Dienstkontos.
10. Klicken Sie auf Schlüssel.
11. Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.

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

13. Klicken Sie auf Schließen.

gcloud

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

   gcloud projects list

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

   Wichtig: Sie müssen das Dienstkonto im selben Projekt erstellen, in der sich die API befindet.

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

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

5. 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 erfordern den 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 finden Sie unter gcloud iam service-accounts finden Sie weitere Informationen zu den Befehlen.

ESP in einem Container ausführen

In diesem Abschnitt wird beschrieben, wie Sie den ESP-Container bereitstellen. Welche Vorgehensweise Sie dazu verwenden, hängt davon ab, wo Sie den ESP-Container bereitstellen:

• ESP lokal in einem Docker-Container oder auf einer anderen Plattform ausführen
• ESP in einem Container auf einem Kubernetes-Cluster ausführen

In den folgenden Beispielen funktioniert die ESP-Option --http_port nur, wenn der gRPC-Dienst für die HTTP-/JSON-Transcodierung konfiguriert ist. Weitere Informationen finden Sie unter HTTP/JSON für gRPC transcodieren.

ESP lokal in einem Docker-Container oder auf einer anderen Plattform ausführen

1. Benennen Sie die JSON-Datei, die den privaten Schlüssel für das Dienstkonto enthält, in service-account-creds.json um und kopieren Sie sie in $HOME/Downloads/, falls sie in ein anderes Verzeichnis heruntergeladen wurde. Auf diese Weise stimmt der vollständige Pfadname mit dem Wert für --service_account_key im nachfolgend beschriebenen Befehl docker run überein.

2. Ersetzen Sie im folgenden docker run-Befehl YOUR_SERVICE_NAME durch den Namen Ihres Dienstes.

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

macOS

Die Docker-Option --net="host" funktioniert unter macOS nicht. Führen Sie stattdessen eine explizite Portzuordnung vom Host zum Container durch. Ersetzen Sie dabei --net="host" durch --publish 8082:8082. Ersetzen Sie außerdem localhost durch den für macOS spezifischen DNS-Namen docker.for.mac.localhost. Weitere Informationen finden Sie in der Docker-Dokumentation im Abschnitt über Anwendungsfälle und Problemumgehungen.

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json
  

Andere Plattform

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json
  

In der folgenden Tabelle werden die Docker-Optionen beschrieben, die in den vorherigen Befehlen verwendet wurden. Informationen zu den im Beispiel verwendeten ESP-Optionen finden Sie unter ESP-Startoptionen.

Option	Beschreibung
--detach	Diese Docker-Option startet den Container im getrennten Modus, sodass er im Hintergrund ausgeführt wird.
--name="esp"	Diese Docker-Option bietet einen leicht zugänglichen Namen für den Container. Sie können beispielsweise docker logs esp ausführen, um Logs aus dem Container aufzurufen.
--net="host"	Diese Docker-Option gibt an, dass der Docker-Container die gleiche Netzwerkkonfiguration wie der Hostcomputer verwenden soll, damit er auf dem Hostcomputer Aufrufe an "localhost" absetzen kann. Mit dieser Option kann ESP nicht lokal auf macOS ausgeführt werden.
--publish=8082:8082	Wenn Sie den ESP unter macOS lokal ausführen möchten, verwenden Sie diese Docker-Option anstelle von --net="host", um eine explizite Portzuordnung vom Host zum Container durchzuführen.
--volume= $HOME/Downloads:/esp	Mit dieser Docker-Option wird Ihr lokales Verzeichnis $HOME/Downloads dem Verzeichnis /esp im Container zugeordnet. Diese Zuordnung wird von der ESP-Option --service_account_key verwendet.

ESP in einem Container auf einem Kubernetes-Cluster ausführen

In diesem Abschnitt wird beschrieben, wie Sie den ESP in einem Kubernetes-Cluster bereitstellen, der sich nicht in Google Cloud befindet.

Damit Ihre API von Endpoints verwaltet wird, stellen Sie den ESP-Container im selben Kubernetes-Pod wie Ihren API-Container bereit. Die Pods, die den ESP und Ihre API ausführen, werden mithilfe einer Labelauswahl wie app: my-api unter einem Kubernetes-Dienst zusammengefasst. Der Kubernetes-Dienst bestimmt die Zugriffsrichtlinie für das Load-Balancing der Clientanfragen an den Proxy-Port.

1. Benennen Sie die JSON-Datei, die den privaten Schlüssel für das Dienstkonto enthält, in service-account-creds.json um und kopieren Sie sie in $HOME/Downloads/, falls sie in ein anderes Verzeichnis heruntergeladen wurde. Dann stimmt der vollständige Pfadname mit dem Befehl im nächsten Schritt überein.

2. Führen Sie den folgenden Befehl aus, um ein Kubernetes-Secret zu erstellen und das Secret als Kubernetes-Volume bereitzustellen:

   kubectl create secret generic service-account-creds \
     --from-file=$HOME/Downloads/service-account-creds.json
   

   Wenn der Vorgang gelingt, wird die folgende Meldung angezeigt: secret "service-account-creds" created

3. Fügen Sie Folgendes in Ihre Kubernetes-Konfigurationsdatei ein und ersetzen Sie YOUR_APP_NAME durch den Namen Ihrer API und YOUR_SERVICE_NAME durch den Namen Ihres Dienstes.

   spec:
   replicas: 1
   template:
     metadata:
       labels:
         app: "YOUR_APP_NAME"
     spec:
       volumes:
         - name: service-account-creds
           secret:
             secretName: service-account-creds
             containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:1
           args: [
             "--http_port=8082",
             "--http2_port=8083",
             "--backend=grpc://127.0.0.1:8081",
             "--service=YOUR_SERVICE_NAME",
             "--rollout_strategy=managed",
             "--service_account_key=/etc/nginx/creds/service-account-creds.json"
           ]
           ports:
             - containerPort: 8080
           volumeMounts:
             - mountPath: /etc/nginx/creds
               name: service-account-creds
               readOnly: true
   

   Informationen zu den im Beispiel verwendeten ESP-Optionen finden Sie unter ESP-Startoptionen.

4. Stellen Sie den ESP in Kubernetes bereit. Ersetzen Sie YOUR_CONFIGURATION_FILE durch den Namen Ihrer Kubernetes-Konfigurationsdatei.

   kubectl apply -f YOUR_CONFIGURATION_FILE

Anfragen senden

Senden Sie einige Anfragen an Ihre API und überprüfen Sie, ob sie den ESP durchlaufen. So können Sie bestätigen, dass die Dienstkontodatei korrekt ist und die Ports richtig zugeordnet sind. Die ESP-Logs rufen Sie mit diesem Befehl auf:

sudo docker logs esp

Die folgenden Beispiele senden Anfragen an die Beispiel-API. Wenn Sie die Beispiel-API nicht verwenden, empfehlen wir die Ausführung ähnlicher Tests.

Sie haben den ESP-Container so konfiguriert, dass er Anfragen am Port 8082 empfängt. Wenn Sie eine Anfrage direkt an den Server unter http://localhost:8080 senden, umgehen die Anforderungen den ESP. Beispiel:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

Response:

  {
    "message": "hello world"
  }

Wenn Sie eine Anfrage an die URL http://localhost:8082 senden, die den ESP durchläuft und keinen API-Schlüssel sendet, lehnt der ESP die Anfrage ab. Beispiel:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

Response:

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

So testen Sie die API mit einem API-Schlüssel:

1. Erstellen Sie auf der Seite API-Anmeldedaten einen API-Schlüssel.
   

   Zur Seite "Domainbestätigung"

2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus.

3. Kopieren Sie den Schlüssel und fügen Sie ihn in die folgende Umgebungsvariablenanweisung ein:

   export KEY=AIza...
   

4. Senden Sie wie folgt eine Anfrage mit dem Schlüssel:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8082/echo?key=$KEY

   Es wird eine erfolgreiche Antwort zurückgegeben:

   {
     "message": "hello world"
   }

Bereinigen

Verwenden Sie das Tool docker, um den Docker-Container esp herunterzufahren und zu entfernen:

    sudo docker stop esp
    sudo docker rm esp

Wenn Sie die bereitgestellte Dienstkonfiguration bereinigen möchten, lesen Sie die Informationen unter API und API-Instanzen löschen.

Nächste Schritte

• SSL-Support für ESP hinzufügen