Extensible Service Proxy-Startoptionen

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 managed oder fixed an. 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. Sie müssen die Option --version nicht angeben, wenn Sie --rollout_strategy auf managed festlegen.
-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. Der Standardwert für die Back-End-Adresse ist 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 der Back-End-Server in Compute Engine in einem Container ausgeführt wird, können Sie den Containernamen und den Port angeben, z. B.
--backend=my-api-container:8000
Wenn Sie angeben möchten, dass das Back-End gRPC-Traffic akzeptiert, fügen Sie das Präfix grpc:// hinzu. Beispiel:
--backend=grpc://127.0.0.1:8000
Wenn der Back-End-Server in Compute Engine in einem Container ausgeführt wird und den gRPC-Traffic akzeptiert, können Sie den Containernamen und den Port angeben, zum 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 den Code 200 für den Speicherort /healthz zurückgibt, statt die Anfrage an das Back-End weiterzuleiten. 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:

Geben Sie folgenden Befehl ein, wenn der ESP so gestartet werden soll, dass er Anfragen am HTTP/1.x-Port 80 und am HTTPS-Port 443 annimmt und die Anfragen an Ihr API-Back-End unter 127.0.0.1:8000 sendet:

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=http://example.com
--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
--cors_allow_origin_regex=^https?://.+\.example\.com$

Der reguläre Ausdruck im vorherigen Beispiel lässt eine Herkunft mit http oder https und einer beliebigen Subdomain von example.com zu.

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_methods=GET,POST,PUT,OPTIONS
--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_headers=Origin,Content-Type,Accept
--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_allow_credentials
--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
--cors_expose_headers=Content-Length

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: