ESP lokal oder auf einer anderen Plattform ausführen

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
  • Prüfen, ob die Sicherheitseinstellungen konfiguriert sind und ordnungsgemäß funktionieren und ob Messwerte und Logs auf der Seite Endpoints > Dienste wie erwartet angezeigt werden

Voraussetzungen

Als Ausgangspunkt wird auf dieser Seite Folgendes vorausgesetzt:

  • 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 dem ESP benötigen, können Sie den Beispielcode aus dem 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 dem 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:

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.

  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. Aktualisieren Sie das Cloud SDK:

    gcloud components update
    
  2. Das Cloud SDK (gcloud) muss für den Zugriff auf Ihre Daten und Dienste auf Google Cloud berechtigt sein:

    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 der ESP die Dienste in der Service Infrastructure. Der ESP muss Zugriffstokens verwenden, um diese Dienste aufzurufen. Wenn Sie den ESP in Google Cloud-Umgebungen wie GKE, Compute Engine oder der flexiblen App Engine-Umgebung bereitstellen, ruft der ESP für Sie Zugriffstokens über den Google Cloud-Metadatendienst ab.

Wenn Sie den ESP 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 dem ESP eine Dienstkonto-JSON-Datei zur Verfügung stellen, die einen privaten Schlüssel enthält. Der ESP verwendet das Dienstkonto, um Zugriffstoken zu generieren und damit die Dienste aufzurufen, die für die Verwaltung der API erforderlich sind.

Sie können entweder die Cloud Console oder das gcloud-Befehlszeilentool verwenden, um das Dienstkonto und die Datei mit dem privaten Schlüssel zu erstellen und dem Dienstkonto die folgenden Rollen zuzuweisen:

Console

  1. Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

    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 Rolle auswählen und wählen Sie Dienstverwaltung > Dienstüberwacher aus.
  8. Klicken Sie auf + Weitere Rolle hinzufügen.
  9. Klicken Sie auf Rolle auswählen und wählen Sie Cloud Trace > Cloud Trace-Agent aus.
  10. Klicken Sie auf Weiter.
  11. Klicken Sie auf + Schlüssel erstellen.
  12. Verwenden Sie im rechten Feld für den Schlüsseltyp den Standardtyp JSON.
  13. Klicken Sie auf Erstellen.
  14. Klicken Sie im Dialogfeld auf Schließen.
  15. Klicken Sie auf Fertig.

Dadurch wird das Dienstkonto erstellt und der private Schlüssel in eine JSON-Datei heruntergeladen.

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
    
  3. Das Cloud SDK (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste auf 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
    
  6. Fügen Sie die Rolle "Dienstüberwacher" hinzu:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/servicemanagement.serviceController
    
  7. Fügen Sie die Rolle "Cloud Trace Agent" hinzu, um Cloud Trace zu aktivieren:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/cloudtrace.agent
    

Weitere Informationen zu den Befehlen finden Sie unter gcloud iam service-accounts.

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

  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 Befehl docker run die Variable 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 \
    --backend=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 \
    --backend=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 \
    --backend=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. Jetzt 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 dabei 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",
              "--backend=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:

Anfrage:

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

Antwort:

    {
      "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:

Anfrage:

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

Antwort:

    {
     "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 "Anmeldedaten"

  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.

Weitere Informationen