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
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:
Beispielcode abrufen
Klonen Sie das Repository der Beispielanwendung auf Ihren lokalen Computer:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:
cd python-docs-samples/endpoints/getting-started
Endpoints konfigurieren
Öffnen Sie im Verzeichnis mit dem Beispielcode die Konfigurationsdatei
openapi.yaml
.Ersetzen Sie im Feld
host
YOUR-PROJECT-ID
durch Ihre Google Cloud-Projekt-ID.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.
gcloud CLI aktualisieren
gcloud components update
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.
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 Dateiopenapi.yaml
angegeben haben.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
Erstellen Sie eine
virtualenv
, aktivieren Sie sie und installieren Sie die Anwendungsabhängigkeiten:virtualenv env
source env/bin/activate
pip install -r requirements.txt
Starten Sie den Server:
python main.py
Öffnen Sie ein anderes Terminalfenster und verwenden Sie
curl
curl 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
- Öffnen Sie in der Google Cloud Console die Seite Dienstkonten.
- Klicken Sie auf Auswählen.
- Wählen Sie das Projekt aus, in dem Ihre API erstellt wurde, und klicken Sie auf Öffnen.
- Klicken Sie auf + Dienstkonto erstellen.
- Geben Sie im Feld Name des Dienstkontos den Namen für das Dienstkonto ein.
- Klicken Sie auf Erstellen.
- Klicken Sie auf Weiter.
- Klicken Sie auf Fertig.
- Klicken Sie auf die E-Mail-Adresse des neu erstellten Dienstkontos.
- Klicken Sie auf Schlüssel.
- Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
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.
Klicken Sie auf Schließen.
gcloud
Geben Sie Folgendes ein, um sich die Projekt-IDs für Ihre Google Cloud-Projekte anzeigen zu lassen:
gcloud projects list
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
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.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.
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
--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
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 Befehldocker run
überein.Ersetzen Sie im folgenden
docker run
-BefehlYOUR_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.
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.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
Fügen Sie Folgendes in Ihre Kubernetes-Konfigurationsdatei ein und ersetzen Sie
YOUR_APP_NAME
durch den Namen Ihrer API undYOUR_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.
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:
Erstellen Sie auf der Seite API-Anmeldedaten einen API-Schlüssel.
Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus.
Kopieren Sie den Schlüssel und fügen Sie ihn in die folgende Umgebungsvariablenanweisung ein:
export KEY=AIza...
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