Der Extensible Service Proxy (ESP) ist ein NGINX-basierter Proxy, mit dem Cloud Endpoints API-Verwaltungsfeatures zur Verfügung stellen kann. Zum Konfigurieren des ESP legen Sie beim Starten des ESP-Docker-Containers Optionen fest. Beim Start des ESP-Containers wird ein Skript mit dem Namen start_esp
aufgerufen, das die NGINX-Konfigurationsdatei mit den von Ihnen angegebenen Optionen schreibt und den ESP startet.
Sie geben ESP-Startoptionen im Befehl docker run
an. Zum Beispiel:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
Wenn Sie den ESP in Kubernetes bereitstellen, geben Sie die Startoptionen in der Manifestdatei für die Bereitstellung im Feld args
an. Beispiel:
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" ]
In der folgenden Tabelle werden die Startoptionen des ESP beschrieben.
Kurze Option | Lange Option | Beschreibung |
---|---|---|
-s SERVICE_NAME |
--service SERVICE_NAME |
Legt den Namen des Endpoints-Dienstes fest. |
-R ROLLOUT_STRATEGY |
--rollout_strategy ROLLOUT_STRATEGY |
Verfügbar ab ESP Version 1.7.0. Geben Sie entweder |
-v CONFIG_ID |
--version CONFIG_ID |
Legt die Dienstkonfigurations-ID fest, die vom ESP verwendet werden soll. Informationen zum Festlegen dieser Option finden Sie unter Dienstname und Konfigurations-ID abrufen.
Wenn Sie --rollout_strategy=fixed angeben oder die Option --rollout_strategy weglassen, müssen Sie die Option --version und eine Konfigurations-ID angeben. In diesem Fall müssen Sie den ESP bei jeder Bereitstellung einer neuen Endpoints-Konfiguration mit der neuen Konfigurations-ID neu starten.
|
-p HTTP1_PORT |
--http_port HTTP1_PORT |
Legt die Ports fest, die vom ESP für HTTP/1.x-Verbindungen verfügbar gemacht werden.1 |
-P HTTP2_PORT |
--http2_port HTTP2_PORT |
Legt die Ports fest, die vom ESP für HTTP/2-Verbindungen verfügbar gemacht werden.1 |
-S SSL_PORT |
--ssl_port SSL_PORT |
Legt die Ports fest, die vom ESP für HTTPS-Verbindungen verfügbar gemacht werden.1 |
-a BACKEND |
--backend BACKEND |
Legt die Adresse für den Back-End-Server für HTTP/1.x-Anwendungen fest. Standardeinstellung
für die Back-End-Adresse lautet http://127.0.0.1:8081 .Sie können auch ein Protokollpräfix angeben. Beispiel: --backend=https://127.0.0.1:8000 Wenn Sie kein Protokollpräfix angeben, wird der Standardwert http verwendet.Wenn Ihr Back-End-Server in Compute Engine in einem Container ausgeführt wird, können Sie Geben Sie den Containernamen und den Port an. Beispiel: --backend=my-api-container:8000 Fügen Sie das Präfix hinzu, um anzugeben, dass das Back-End gRPC-Traffic akzeptiert. grpc:// Beispiel: --backend=grpc://127.0.0.1:8000 Wenn Ihr Back-End-Server in Compute Engine in einem Container ausgeführt wird, und gRPC-Traffic akzeptiert, Geben Sie den Containernamen und den Port an. Beispiel: --backend=grpc://my-api-container:8000
|
-N STATUS_PORT |
--status_port STATUS_PORT |
Legt den Statusport fest (Standard: 8090 ).
|
– | --disable_cloud_trace_auto_sampling |
Standardmäßig ist aktiviert, dass der ESP mithilfe von Cloud Trace Stichproben sammelt, und zwar im Umfang von einer Anfrage pro 1.000 Anfragen oder einer Anfrage pro 10 Sekunden. Setzen Sie dieses Flag, um die automatische Probenahme zu deaktivieren. Cloud Trace kann unabhängig von diesem Flag-Wert auch über Anfrage-HTTP-Header mit Trace-Kontext aktiviert werden. Weitere Informationen finden Sie unter API-Tracing. |
-n NGINX_CONFIG |
--nginx_config NGINX_CONFIG |
Legt den Speicherort für die benutzerdefinierte NGINX-Konfigurationsdatei fest. Wenn Sie diese Option angeben, ruft der ESP die angegebene Konfigurationsdatei ab und startet direkt NGINX mit der bereitgestellten benutzerdefinierten Konfigurationsdatei. Weitere Informationen finden Sie unter Benutzerdefinierte nginx-Konfiguration für GKE verwenden. |
-k SERVICE_ACCOUNT_KEY |
--service_account_key SERVICE_ACCOUNT_KEY |
Legt die JSON-Datei mit den Anmeldedaten für das Dienstkonto fest. Sofern angegeben, erzeugt der ESP mithilfe des Dienstkontos ein Zugriffstoken für den Aufruf von Service Infrastructure APIs. Diese Option muss nur angegeben werden, wenn der ESP auf anderen Plattformen als Google Cloud ausgeführt wird, beispielsweise auf Ihrem lokalen Computer, in Kubernetes oder mit einem anderen Cloud-Anbieter. Weitere Informationen finden Sie unter Dienstkonto erstellen. |
-z HEALTHZ_PATH |
--healthz HEALTHZ_PATH |
Legen Sie für die Systemdiagnose einen Endpunkt an denselben Ports fest wie für das Anwendungs-Back-End. Zum Beispiel führt -z healthz dazu, dass der ESP
Code 200 für
/healthz , anstatt die Anfrage an den
Back-End. Standardeinstellung: nicht verwendet.
|
– | --dns DNS_RESOLVER |
Geben Sie einen DNS-Resolver an. --dns 169.254.169.254 verwendet beispielsweise den GCP-Metadatenserver als DNS-Resolver. Falls nicht angegeben, ist der Standardwert 8.8.8.8 .
|
1 Diese Ports sind optional und müssen sich voneinander unterscheiden.
Wenn Sie keine Portoption angeben, akzeptiert der ESP HTTP/1.x-Verbindungen an Port 8080
.
Bei HTTPS-Verbindungen erwartet der ESP, dass sich die TLS-Secrets in /etc/nginx/ssl/nginx.crt
und /etc/nginx/ssl/nginx.key
befinden.
Beispiele für Befehlszeilenaufrufe
Die folgenden Beispiele veranschaulichen die Verwendung verschiedener Befehlszeilenargumente:
ESP wird gestartet, damit er Anfragen verarbeitet, die am HTTP/1.x-Port 80
eingehen.
und HTTPS-Port 443
und senden Sie die Anfragen an Ihr API-Back-End unter
127.0.0.1:8000
:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --http_port=80 \ --ssl_port=443 \ --backend=127.0.0.1:8000
Geben Sie folgenden Befehl ein, wenn der ESP mit einer benutzerdefinierten NGINX-Konfiguration gestartet werden soll. Dabei wird die Datei mit den Anmeldedaten des Dienstkontos verwendet, um die Dienstkonfiguration abzurufen und eine Verbindung zur Dienststeuerung herzustellen:
sudo docker run \ --detach \ --volume=$HOME/Downloads:/esp \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --service_account_key=/esp/serviceaccount.json \ --nginx_config=/esp/nginx.conf
Verwenden Sie das Docker-Flag --volume
oder --mount
, um die JSON-Datei mit dem privaten Schlüssel für das Dienstkonto und die benutzerdefinierte NGINX-Konfigurationsdatei als Volumes im ESP-Docker-Container bereitzustellen. Im obigen Beispiel wird das Verzeichnis $HOME/Downloads
auf dem lokalen Computer dem Verzeichnis esp
im Container zugeordnet. Wenn Sie die Datei mit dem privaten Schlüssel für das Dienstkonto speichern, wird sie normalerweise in das Verzeichnis Downloads
heruntergeladen. Allerdings können Sie die Datei mit dem privaten Schlüssel bei Bedarf in ein anderes Verzeichnis kopieren. Weitere Informationen finden Sie unter
Daten in Docker verwalten
.
CORS-Unterstützung zum ESP hinzufügen
Unter Support-CORS finden Sie eine Beschreibung der verfügbaren CORS-Supportoptionen. In diesem Abschnitt wird die Verwendung von ESP-Start-up-Flags zur Unterstützung von CORS beschrieben.
Fügen Sie die Option --cors_preset
ein und setzen Sie sie auf basic
oder cors_with_regex
, um die CORS-Unterstützung im ESP zu aktivieren. Wenn Sie --cors_preset=basic
oder --cors_preset=cors_with_regex
verwenden:
- geht ESPv2Beta davon aus, dass alle Standortpfade die gleiche CORS-Richtlinie haben.
- antwortet es sowohl auf einfache als auch auf Preflight-
HTTP OPTIONS
-Anfragen. - speichert ESPv2 Beta das Ergebnis der Preflight-
OPTIONS
-Anfrage bis zu 20 Tage (1.728.000 Sekunden) im Cache. legt ESPv2 Beta für die Antwortheader folgende Werte fest:
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization Access-Control-Expose-Headers: Content-Length,Content-Range
Geben Sie eine der folgenden Optionen an, um den Standardwert von Access-Control-Allow-Origin
zu überschreiben:
Option | Beschreibung |
---|---|
--cors_allow_origin |
Wird mit --cors_preset=basic verwendet, um für Access-Control-Allow-Origin eine bestimmte Herkunft festzulegen.Beispiel:
--cors_preset=basic
|
--cors_allow_origin_regex |
Wird mit --cors_preset=cors_with_regex verwendet und ermöglicht Ihnen, Access-Control-Allow-Origin mit einem regulären Ausdruck festzulegen.Beispiel:
--cors_preset=cors_with_regex
Der reguläre Ausdruck im vorherigen Beispiel lässt eine Herkunft mit |
Nachdem Sie --cors_preset=basic
oder --cors_preset=cors_with_regex
entsprechend festgelegt haben, um CORS zu aktivieren, können Sie die Standardwerte der anderen Antwortheader dadurch überschreiben, dass Sie eine oder mehrere der folgenden Optionen angeben:
Option | Beschreibung |
---|---|
--cors_allow_methods |
Legt für Access-Control-Allow-Methods die angegebenen HTTP-Methoden fest. Geben Sie die HTTP-Methoden als String an, wobei diese jeweils durch ein Komma getrennt sind.Beispiel:
--cors_preset=basic
|
--cors_allow_headers |
Legt für Access-Control-Allow-Headers die angegebenen HTTP-Header fest. Geben Sie die HTTP-Header als String an, wobei diese jeweils durch ein Komma getrennt sind.Beispiel:
--cors_preset=basic
|
--cors_allow_credentials |
Gibt an, dass der Header Access-Control-Allow-Credentials mit dem Wert true in den Antworten enthalten ist. Standardmäßig ist der Header Access-Control-Allow-Credentials nicht in den Antworten enthalten.Beispiel:
--cors_preset=basic
|
--cors_expose_headers |
Legt für Access-Control-Expose-Headers die angegebenen Header fest. Geben Sie an, welche Header als Bestandteil der Antwort als String angezeigt werden sollen, wobei die Header jeweils durch ein Komma getrennt sind.Beispiel:
--cors_preset=basic
|
Wenn die CORS-Startoptionen des ESP nicht den Anforderungen Ihrer Anwendung entsprechen, können Sie eine benutzerdefinierte nginx.conf
-Datei mit der CORS-Unterstützung erstellen, die die Anwendung benötigt. Weitere Informationen finden Sie unter Benutzerdefinierte nginx.conf
zur Unterstützung von CORS erstellen.
Weitere Informationen
Erfahren Sie mehr über:
- ESP und API-Back-End in Google Cloud bereitstellen
- ESP lokal oder auf einer anderen Plattform ausführen
- Das Skript
start_esp
auf GitHub