Extensible Service Proxy-Startoptionen

OpenAPI | gRPC

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.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Legt die Ports fest, die vom ESP für HTTP/2-Verbindungen verfügbar gemacht werden.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Legt die Ports fest, die ESP für HTTPS-Verbindungen verfügbar macht.¹
`-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 Ihr Back-End-Server in Compute Engine in einem Container ausgeführt wird, können Sie den Containernamen und den Port angeben. Beispiel: `--backend=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. Beispielsweise führt `-z healthz` dazu, dass der ESP den Code `200` für den Speicherort `/healthz` zurückgibt, anstatt 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`.

¹ 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:

So starten Sie den ESP so, dass er Anfragen am HTTP/1.x-Port 80 und am HTTPS-Port 443 verarbeitet und die Anfragen an das API-Back-End unter 127.0.0.1:8000 senden:

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.

Nächste Schritte

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