Extensible Service Proxy V2-Startoptionen

Extensible Service Proxy V2 (ESPv2) ist ein auf Envoy beruhender Proxy, über den Cloud Endpoints Ihnen API-Verwaltungsfeatures zur Verfügung stellen kann. Zum Konfigurieren von ESPv2 können Sie beim Bereitstellen des ESPv2-Dienstes Konfigurations-Flags angeben.

Konfigurations-Flags festlegen

Die Methode zum Festlegen von ESPv2-Konfigurations-Flags hängt von der Bereitstellungsplattform ab, wie in den folgenden Abschnitten beschrieben.

Compute Engine-VM

ESPv2-Konfigurations-Flags für Compute Engine werden im Befehl docker run angegeben. Beispiel:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

In diesem Beispiel sind --service, --rollout_strategy und --backend die ESPv2-Konfigurations-Flags.

GKE und Kubernetes

Sie können Konfigurations-Flags für GKE und Kubernetes im Feld args der Manifestdatei der Bereitstellung angeben. Beispiel:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

In diesem Beispiel sind --listener_port, --backend, --service und --rollout_strategy die ESPv2-Konfigurations-Flags.

Cloud Run für serverlose Plattformen

Zum Festlegen der Start-up-Optionen für Cloud Run für serverlose Server verwenden Sie die Umgebungsvariable ESPv2_ARGS. Die Variable kann im Befehl gcloud run deploy mithilfe der Option --set-env-vars festgelegt werden.

Beispiel:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

In diesem Beispiel ist --enable_debug das ESPv2-Konfigurations-Flag.

Weitere Informationen zum Befehl gcloud run deploy finden Sie unter Cloud Functions für OpenAPI, Cloud Run für OpenAPI oder Cloud Run für gRPC.

Um mehrere Argumente in der Umgebungsvariable ESPv2_ARGS festzulegen, geben Sie ein benutzerdefiniertes Trennzeichen an, um damit mehrere Argumente zu trennen. Verwenden Sie kein Komma als Trennzeichen. Setzen Sie das benutzerdefinierte Trennzeichen zwischen Caret-Zeichen an den Anfang der Umgebungsvariablen ESPv2_ARGS.

Im folgenden Beispiel wird ++ als Trennzeichen verwendet:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

Wenn das von Ihnen festgelegte Flag Kommata enthält, müssen Sie die Umgebungsvariable ESPv2_ARGS im Skript gcloud_build_image festlegen.

So fügen Sie beispielsweise das Flag --cors_allow_methods=PUT,POST,GET hinzu:

  • Laden Sie das Skript gcloud_build_image herunter.
  • Bearbeiten Sie gcloud_build_image wie unten gezeigt:
    cat <<EOF > Dockerfile
      FROM BASE_IMAGE
    
      ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
      COPY service.json \ENDPOINTS_SERVICE_PATH
    
      ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
    
      ENTRYPOINT ["/env_start_proxy.py"]
      EOF
  • Führen Sie das Skript gcloud_build_image aus, um das Image zu erstellen.

ESPv2-Konfigurations-Flags

ESPv2-Konfigurations-Flags können in folgende Kategorien gruppiert werden:

Weitere allgemeine Beispiele und Hilfetexte für ESPv2-Flags finden Sie im GitHub-Repository.

Nicht serverlose Konfiguration

Diese Flags sind erforderlich, um ESPv2 auf nicht serverlosen Plattformen wie GKE, Compute Engine und Kubernetes auszuführen. Sie können nicht festgelegt werden, wenn sie in Cloud Run für serverlose Plattformen bereitgestellt wurden.

Flag Beschreibung
--service Legt den Namen des Endpoints-Dienstes fest.
--version Legt die Dienstkonfigurations-ID des Endpoints-Dienstes fest.
--rollout_strategy Gibt die Rollout-Strategie für die Dienstkonfiguration an [fixed|managed]. Der Standardwert ist fixed.
--listener_port Gibt den Port für die nachgelagerte Verbindungen an. Es unterstützt HTTP/1.x-, HTTP/2- und gRPC-Verbindungen. Der Standardwert ist 8080.
--backend Gibt die Adresse des lokalen Back-End-Anwendungsservers an. Gültige Schemas sind http, https, grpc und grpcs, falls vorhanden. Das Standardschema ist >http.

Logging

Mit diesen Flags können Sie ESPv2 so konfigurieren, dass zusätzliche Informationen in das Stackdriver-Log geschrieben werden.

Flag Beschreibung
--log_request_headers

Die Werte der angegebenen Anfrageheader werden erfasst. Die Liste der Anfrageheader wird durch Kommas getrennt und ohne Leerzeichen angegeben. Setzen Sie dieses Flag beispielsweise auf:

--log_request_headers=foo,bar

Wenn in der Anfrage Werte für die Header „foo“ und „bar“ verfügbar sind, enthält das Endpoints-Log Folgendes:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Die Werte der angegebenen Antwortheader werden erfasst. Die Liste der Antwortheader wird durch Kommas getrennt und ohne Leerzeichen angegeben. Setzen Sie dieses Flag beispielsweise auf:

--log_response_headers=baz,bing

Wenn in der Antwort Werte für die Header „baz“ und „bing“ verfügbar sind, enthält das Endpoints-Log Folgendes:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Die Werte der angegebenen einfachen Felder der JWT-Nutzlast werden erfasst. Die Liste der Felder wird durch Kommas getrennt und ohne Leerzeichen angegeben. Setzen Sie dieses Flag beispielsweise auf:

--log_jwt_payload=sub,project_id,foo.foo_name

Wenn die Werte in der JWT-Nutzlast verfügbar sind, enthält das Endpoints-Log Folgendes:

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

Die Werte in der JWT-Nutzlast müssen einfache Felder sein (String, Ganzzahl). JSON-Objekte und -Arrays werden nicht erfasst.

--access_log

Wenn dieses Flag angegeben ist, wird der Pfad zu der lokalen Datei angegeben, in die Zugriffslogeinträge geschrieben werden.

--access_log_format

Stringformat, um das Format des Zugriffslogs anzugeben. Wenn kein Wert festgelegt ist, wird der >String im Standardformat verwendet. Die detaillierte Formatgrammatik finden Sie in der Referenz zu Formatstrings.

Tracing

Verwenden Sie diese Flags, um die an Stackdriver gesendeten Tracing-Daten von ESPv2 zu konfigurieren. Diese Flags gelten nur, wenn Tracing aktiviert ist.

Flag Beschreibung
--disable_tracing

Tracing wird deaktiviert. Standardmäßig ist Tracing aktiviert.

Bei Aktivierung nimmt ESPv2 jede Sekunde eine kleine Anzahl von Anfragen an Ihre API als Stichprobe, um Traces zu erhalten. Diese werden dann an Stackdriver Trace gesendet. Standardmäßig wird 1 von 1.000 Anfragen als Stichprobe verwendet. Mit dem Flag --tracing_sample_rate können Sie die Rate der Stichproben ändern.

--tracing_project_id

Die Google-Projekt-ID für Stackdriver Tracing.

Tracing ist ein kostenpflichtiger Dienst. Das angegebene Projekt wird für das Tracing in Rechnung gestellt.

Standardmäßig wird dafür die Projekt-ID des bereitgestellten ESPv2-Dienstes berechnet.

Die Projekt-ID wird durch Aufrufen des Metadatenservers für Google Cloud-Instanzen beim Start bestimmt. Wenn ESPv2 außerhalb von Google Cloud (mit dem Flag --non_gcp) bereitgestellt wird, wird das Tracing automatisch deaktiviert, sofern dieses Flag nicht explizit festgelegt ist.

--tracing_sample_rate

Die Rate der Trace-Stichproben wird auf einen Wert zwischen 0,0 und 1,0 festgelegt. Dieser Wert gibt den Anteil der Anfragen an, die als Stichprobe genommen werden.

Der Standardwert ist 0,001, was einer von 1.000 Anfragen entspricht.

--tracing_incoming_context

Dieses Flag gibt an, welche HTTP-Header auf den Trace-Kontext geprüft werden sollen. Die Liste der Flag-Werte muss durch Kommata und ohne Leerzeichen getrennt werden. Beachten Sie, dass die Reihenfolge wichtig ist: Der Trace-Kontext wird vom ersten übereinstimmenden Header abgeleitet.

Mögliche-Werte sind traceparent, x-cloud-trace-context und grpc-trace-bin.

Wenn nichts angegeben ist, werden die Header traceparent und x-cloud-trace-context (in dieser Reihenfolge) geprüft.

Weitere Informationen finden Sie unter API-Tracing.

--tracing_outgoing_context

Bestimmt den Header des Trace-Kontexts in der an den Backend-Dienst gesendeten Anfrage.

Dieses Flag gibt an, welcher HTTP-Header festzulegen ist. Die Werte werden durch Kommas getrennt und ohne Leerzeichen angegeben.

Mögliche-Werte sind traceparent, x-cloud-trace-context und grpc-trace-bin.

Wenn Sie das Flag weglassen, werden die Header traceparent und x-cloud-trace-context gesendet.

Weitere Informationen finden Sie unter API-Tracing.

Systemdiagnose

Verwenden Sie diese Flags, um Systemdiagnosen für ESPv2 zu konfigurieren. Mit dem ersten Flag kann ein Integritäts-Handler eingerichtet werden, der auf die Systemdiagnoseaufrufe reagiert. Mit den anderen Flags können Sie Systemdiagnosen für das gRPC-Backend aktivieren.

/tbody>
Flag Beschreibung
-z, --healthz Legen Sie einen Endpunkt für die Systemdiagnose fest. Zum Beispiel führt -z healthz dazu, dass ESPv2 den Code 200 für den Pfad /healthz zurückgibt.
--health_check_grpc_backend Aktivieren Sie ESPv2, um den gRPC-Systemdiagnosedienst regelmäßig auf ein Backend zu prüfen, das durch das Flag --backend angegeben wird. Das Backend muss das gRPC-Protokoll verwenden und das gRPC-Systemdiagnoseprotokoll implementieren. Der Systemdiagnose-Endpunkt, der durch das Flag --healthz aktiviert ist, spiegelt das Ergebnis der Backend-Systemdiagnose wider.
--health_check_grpc_backend_service Geben Sie den Dienstnamen an, wenn Sie das Backend gRPC-Systemdiagnoseprotokoll aufrufen. Der Wert dieses Flags wird nur angewendet, wenn das Flag --health_check_grpc_backend verwendet wird. Es ist optional, wenn nicht festgelegt, ist der Standardwert leer. Ein leerer Dienstname dient dazu, den Gesamtzustand des gRPC-Servers abzufragen.
--health_check_grpc_backend_interval Geben Sie beim Aufrufen des Backend-gRPC-Systemdiagnosedienstes das Überprüfungsintervall und das Zeitlimit für Anfragen an. Der Wert dieses Flags wird nur angewendet, wenn das Flag --health_check_grpc_backend verwendet wird. Der Standardwert beträgt 1 Sekunde. Das akzeptierte Format ist eine Sequenz von Dezimalzahlen mit jeweils optionalem Bruchteil und Einheitssuffix, z. B. "5s", "100ms" oder "2m". Gültige Zeiteinheiten sind "m" für Minuten, "s" für Sekunden und "ms" für Millisekunden.

Debugging

Verwenden Sie diese Flags, um das Debugging für ESPv2 zu konfigurieren. Mit diesen Flags können Sie einen Envoy-Admin-Port einrichten, um Konfiguration und Statistiken abzurufen oder Envoy im Debug-Modus auszuführen, um Informationen auf Debug-Ebene in das Log zu schreiben.

Flag Beschreibung
--status_port, --admin_port Aktivieren Sie den ESPv2 Envoy-Administrator auf diesem Port. Weitere Informationen finden Sie in der Referenz zur Envoy-Administrationsoberfläche. Der Administratorport ist standardmäßig deaktiviert.
--enable_debug Protokolle auf Debug-Ebene aktivieren und Debug-Header hinzufügen.

Nicht-Google Cloud-Bereitstellung

Wenn ESPv2 nicht in einer Google Cloud-Umgebung bereitgestellt wird, sind möglicherweise die folgenden Flags erforderlich.

Flag Beschreibung
--service_account_key

Gibt die JSON-Datei des Dienstkontoschlüssels für den Zugriff auf Google-Dienste an. Wenn die Option nicht angegeben ist, kontaktiert der Proxy den Google Cloud-Metadatenserver, um ein Zugriffstoken abzurufen.

--dns_resolver_addresses Die Adressen von DNS-Resolvern. Jede Adresse sollte das Format IP_ADDR oder IP_ADDR:PORT haben und durch ein Semikolon (;) getrennt sein. Für IP_ADDR wird der Standard-DNS-Port 52 verwendet. Beispiel: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) Wenn nichts festgelegt ist, verwendet ESPv2 den in /etc/resolv.conf konfigurierten Standard-Resolver.
--backend_dns_lookup_family Definieren Sie die DNS-Lookup-Familie für alle Back-Ends. Folgende Optionen sind verfügbar: auto, v4only, v6only, v4preferred und all. Die Standardeinstellung ist v4preferred. Beachten Sie, dass auto ein veralteter Wert ist. Wenn das Flag auf auto gesetzt ist, entspricht das Verhalten dem von v6preferred.
--non_gcp Standardmäßig versucht der Proxy, eine Verbindung zum Google Cloud-Metadatenserver herzustellen, um den VM-Standort in den ersten Anfragen zu ermitteln. Um diesen Schritt zu überspringen, setzen Sie dieses Flag auf true.

Lokales Testen

ESPv2 kann zu Testzwecken lokal auf Ihrer Workstation bereitgestellt werden. Weitere Informationen finden Sie unter ESP lokal oder auf einer anderen Plattform ausführen.

Verwenden Sie diese Flags zusammen mit den Flags für Bereitstellungen außerhalb von Google Cloud, um die lokale Bereitstellung und das Testen im Rahmen der Continuous Integration zu vereinfachen.

Flag Beschreibung
--service_json_path

Geben Sie einen Pfad für ESPv2 zum Laden der Endpunkt-Dienstkonfiguration an. Mit diesem Flag verwendet ESPv2 eine "festgelegte“ Rollout-Strategie und die folgenden Flags werden ignoriert:

  • --service
  • --version
  • --rollout_strategy

Dieses Flag verhindert, dass ESPv2 das Kontingent für die Service Management API nutzt.

--enable_backend_address_override

Backend-Adressen können entweder mit dem --backend-Flag oder dem backend.rule.address-Feld in der Dienstkonfiguration angegeben werden. Beachten Sie bei OpenAPI-Nutzern, dass das backend.rule.address-Feld durch das address-Feld in der x-google-backend-Erweiterung festgelegt wird.

Die Dienstkonfiguration pro Vorgang, backend.rule.address, wird normalerweise für serverloses Routing angegeben. Standardmäßig hat backend.rule.address für jeden einzelnen Vorgang vor dem --backend-Flag Vorrang.

Aktivieren Sie dieses Flag, wenn das Flag --backend stattdessen Vorrang haben soll. Dies ist nützlich, wenn Sie auf einer lokalen Workstation entwickeln. Sie können dann dieselbe Produktionsdienstkonfiguration verwenden, aber die Backend-Adresse für lokale Tests über das Flag --backend überschreiben.

Hinweis: Nur die Adresse wird überschrieben. Alle anderen Komponenten von backend.rule gelten weiterhin (Zeitlimits, Backend-Authentifizierung, Pfadübersetzung usw.).

Client IP-Extraktion

Verwenden Sie diese Flags, um die Client IP-Extraktion für ESPv2 zu konfigurieren.

Flag Beschreibung
--envoy_use_remote_address

Weitere Informationen zur Konfiguration von Envoy HttpConnectionManager finden Sie in der Referenz zu Envoy. Der Standardwert ist Aus.

--envoy_xff_num_trusted_hops Weitere Informationen zur Konfiguration von Envoy HttpConnectionManager finden Sie in der Referenz zu Envoy. Der Standardwert liegt bei 2.

CORS-Unterstützung

Unter Support-CORS finden Sie eine Beschreibung der verfügbaren CORS-Supportoptionen. In diesem Abschnitt wird die Verwendung von ESPv2-Start-up-Flags zur Unterstützung von CORS beschrieben.

Zum Aktivieren der CORS-Unterstützung in ESPv2 geben Sie die Option --cors_preset an und legen eines der folgenden Flags fest:

  • --cors_preset=basic
  • --cors_preset=cors_with_regex

Wenn Sie --cors_preset=basic oder --cors_preset=cors_with_regex angeben, dann geht ESPv2 davon aus:

  • 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
    Access-Control-Max-Age: 1728000
    

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 eine beliebige Subdomain von example.com zu.

Wenn Sie diese Option in einer Kubernetes-Konfigurationsdatei festlegen, müssen Sie einen zusätzlichen umgekehrten Schrägstrich hinzufügen, um beide Instanzen von \ im String zu maskieren. Beispiel:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

Wenn Sie diese Option im Skript gcloud_build_image für Cloud Run festlegen, versuchen Sie, keine Escapezeichen und umgekehrte Schrägstriche zu verwenden, da sie beim Start vom Bash-Skript möglicherweise nicht korrekt übergeben werden. Verwenden Sie Zeichenklassen anstelle von Metasequenzen. Beispiel: Original: \d Recommended: [0-9]

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
--cors_max_age Legt für Access-Control-Max-Age die angegebene Zeitdauer fest. Das zulässige Format ist eine Sequenz von Dezimalzahlen, die jeweils einen optionalen Bruchwert und ein Einheitensuffix haben, z. B. "300 m", "1,5 h" oder "2 h 45 m". Gültige Zeiteinheiten sind "m" für Minuten und "h" für Stunden. Der Standardwert ist "480h", wenn er nicht festgelegt wird.
Beispiel:
--cors_preset=basic
--cors_max_age=24h

TLS-Support

Verwenden Sie diese Flags, um ESPv2 für die Verwendung von TLS-Verbindungen zu konfigurieren.

Flag Beschreibung
--ssl_server_cert_path Pfad des Serverzertifikats. Bei der Konfiguration akzeptiert ESPv2 nur sichere Verbindungen über HTTP/1.x und HTTP/2 über listener_port. Erfordert das Zertifikat und die Schlüsseldateien "server.crt" und "server.key" in diesem Pfad.
--ssl_server_cipher_suites Cipher Suites für nachgelagerte Verbindungen, als durch Kommas getrennte Liste angegeben. Weitere Informationen finden Sie unter Cipher Suite-Konfiguration.
--ssl_backend_client_cert_path Pfad des Clientzertifikats des Proxys. Mit der Konfiguration aktiviert ESPv2 die TLS-Authentifizierung für HTTPS-Back-Ends. Erfordert das Zertifikat und die Schlüsseldateien "client.crt" und "client.key" in diesem Pfad.
--ssl_backend_client_root_certs_file Der Dateipfad der Root-Zertifikate, mit denen ESPv2 das Back-End-Serverzertifikat prüft. Wenn nicht angegeben, verwendet ESPv2 standardmäßig „/etc/ssl/certs/ca-certificates.crt“.
--ssl_backend_client_cipher_suites Cipher Suites für HTTPS-Back-Ends, als durch Kommas getrennte Liste angegeben. Weitere Informationen finden Sie unter Cipher Suite-Konfiguration.
--ssl_minimum_protocol Mindestversion des TLS-Protokolls für die clientseitige Verbindung. Weitere Informationen finden Sie hier
--ssl_maximum_protocol Maximale TLS-Protokollversion für clientseitige Verbindung. Weitere Informationen finden Sie hier
--enable_strict_transport_security Aktivieren Sie HSTS (HTTP Strict Transport Security). Antwort-Header "Strict-Transport-Security" mit dem Wert "max-age=31536000; includeSubdomains;" wird für alle Antworten hinzugefügt.
--generate_self_signed_cert Generieren Sie zu Beginn ein selbst signiertes Zertifikat und einen Schlüssel und speichern Sie diese dann in "/tmp/ssl/endpoints/server.crt" und "/tmp/ssl/endpoints/server.key". Dies ist nützlich, wenn zum Verarbeiten von HTTPS-Anfragen nur ein zufälliges selbst signiertes Zertifikat benötigt wird. Das generierte Zertifikat hat den Common Name "localhost" und ist zehn Jahre gültig.

Zeitlimits und Wiederholungsversuche

Mit diesen Flags können Sie für ESPv2 das Zeitlimit für HTTP-Aufrufe konfigurieren und wiederholen.

Flag Beschreibung
--http_request_timeout_s

Legt das Zeitlimit in Sekunden für Anfragen an externe Dienste außer Back-End und Google Service Control fest. Es umfasst Google Service Management, Metadatenserver und den Google IAM-Server. Muss > 0 sein und der Standardwert ist 30 Sekunden, wenn nicht festgelegt.

--service_control_network_fail_open

Falls beim Herstellen einer Verbindung zu Google Service Control Netzwerkfehler auftreten, sind Anfragen zulässig, wenn dieses Flag aktiviert ist. Die Standardeinstellung ist Ein.

--service_control_check_timeout_ms Legen Sie das Zeitlimit in Millisekunden für die Service Control-Diagnoseanfrage fest. Muss > 0 sein und der Standardwert ist 1.000, wenn nicht festgelegt.
--service_control_report_timeout_ms Legen Sie das Zeitlimit in Millisekunden für die Service Control-Berichtsanfrage fest. Muss > 0 sein und der Standardwert ist 1.000, wenn nicht festgelegt.
--service_control_quota_timeout_ms Legen Sie das Zeitlimit in Millisekunden für die Service Control-Kontingentanfrage fest. Muss > 0 sein und der Standardwert ist 1.000, wenn nicht festgelegt.
--service_control_check_retries Legen Sie die Wiederholungsversuche für die Service Control-Berichtsanfrage fest. Muss >= 0 sein und der Standardwert ist 3, wenn nicht festgelegt.
--service_control_report_retries Legen Sie die Wiederholungsversuche für die Service Control-Berichtsanfrage fest. Muss >= 0 sein und der Standardwert ist 5, wenn nicht festgelegt.
--service_control_quota_retries Legen Sie die Wiederholungsversuche für die Service Control-Kontingentanfrage fest. Muss >= 0 sein und der Standardwert ist 1, wenn nicht festgelegt.
--backend_retry_ons

Die Bedingungen, unter denen ESPv2 eine Wiederholung auf den Back-Ends versucht. Sie können eine oder mehrere retryOn-Bedingungen mit einer durch Kommas getrennten Liste angeben. Der Standardwert ist reset,connect-failure,refused-stream. Um die Wiederholung zu deaktivieren, lassen Sie dieses Flag leer.

Unter folgenden Links finden Sie die akzeptierten Bedingungen:

--backend_retry_num Die zulässige Anzahl an Wiederholungsversuchen. Muss >= 0 sein und ist standardmäßig 1.

gRPC-Transcodierung

Verwenden Sie diese Flags, um ESPv2 für die Transcodierung von HTTP/JSON zu gRPC zu konfigurieren.

Flag Beschreibung
--transcoding_always_print_primitive_fields

Gibt an, ob einfache Felder für die grpc-json-Transcodierung gedruckt werden. Standardmäßig werden einfache Felder mit Standardwerten in der JSON-Ausgabe ausgelassen. Beispiel: Ein int32-Feld mit dem Wert 0 wird nicht ausgeführt. Wenn Sie dieses Flag auf true setzen, wird das Standardverhalten überschrieben und die einfachen Felder ausgegeben, unabhängig von ihren Werten. Die Standardeinstellung ist false.

--transcoding_always_print_enums_as_ints

Gibt an, ob Enums als Ganzzahlen für die grpc-json-Transcodierung gedruckt werden. Standardmäßig werden sie als Strings gerendert. Die Standardeinstellung ist false.

--transcoding_stream_newline_delimited

Wenn „true“, verwenden Sie ein neues Zeilentrennzeichen, um die Antwortstreamingnachrichten zu trennen. Bei „false“ werden alle Antwortstreamingnachrichten in ein JSON-Array transcodiert.

--transcoding_case_insensitive_enum_parsing

Normalerweise sollten Proto-Enum-Werte bei Verwendung in JSON in Großbuchstaben angegeben werden. Setzen Sie dieses Flag auf „true“, wenn in der JSON-Anfrage enum-Werte ohne Großbuchstaben verwendet werden.

--transcoding_preserve_proto_field_names

Gibt an, ob Proto-Feldnamen für die grpc-json-Transcodierung beibehalten werden sollen. Standardmäßig generiert protobuf die JSON-Feldnamen mit der Option json_name (oder niedrigerem Kamel) in dieser Reihenfolge. Wenn Sie dieses Flag festlegen, werden die ursprünglichen Feldnamen beibehalten. Die Standardeinstellung ist false.

--transcoding_ignore_query_parameters

Eine Liste mit durch Kommas getrennten Abfrageparametern, die für die Zuordnung von Transcodierungsmethoden in der grpc-json-Transcodierung ignoriert werden. Standardmäßig transcodiert der Transcoder-Filter eine Anfrage nicht mit unbekannten/ungültigen Abfrageparametern.

--transcoding_ignore_unknown_query_parameters

Gibt an, ob Abfrageparameter ignoriert werden, die keinem entsprechenden protobuf-Feld in der grpc-json-Transcodierung zugeordnet werden können. Verwenden Sie diese Option, wenn Sie die Abfrageparameter nicht steuern können und sie Ihnen vorher nicht bekannt sind. Verwenden Sie andernfalls --transcoding_ignore_query_parameters. Die Standardeinstellung ist false.

--transcoding_query_parameters_disable_unescape_plus

Standardmäßig wird das Pluszeichen "+" in den Abfrageparametern in der grpc-json-Transcodierung in den Bereich " " nicht maskiert. Dies unterstützt HTML 2.0. Wenn dies nicht erwünscht ist, legen Sie dieses Flag auf "true" fest, um diese Funktion zu deaktivieren.

Anfrage- und Antwortänderung

Verwenden Sie diese Flags, um ESPv2 so zu konfigurieren, dass Anfragen und Antworten teilweise geändert werden.

Flag Beschreibung
--add_request_header

Fügen Sie der Anfrage einen HTTP-Header hinzu, bevor Sie sie an das vorgelagerte Backend senden. Ist der Header bereits in der Anfrage enthalten, so wird sein Wert durch den neuen ersetzt.

Benutzerdefinierte Envoy-Variablen werden unterstützt.

Dieses Argument kann mehrmals wiederholt werden, um mehrere Header anzugeben. Beispiel:
--add_request_header=key1=value1
--add_request_header=key2=value2
.

--append_request_header

Hängen Sie einen HTTP-Header an die Anfrage an, bevor Sie sie an das vorgelagerte Backend senden. Ist der Header bereits in der Anfrage enthalten, wird der neue Wert angehängt.

Benutzerdefinierte Envoy-Variablen werden unterstützt.

Dieses Argument kann mehrmals wiederholt werden, um mehrere Header anzugeben. Beispiel:
--append_request_header=key1=value1
--append_request_header=key2=value2
.

--add_response_header

Fügen Sie der Antwort einen HTTP-Header hinzu, bevor Sie sie an den nachgelagerten Client senden. Ist der Header bereits in der Antwort enthalten, wird er durch den neuen ersetzt.

Benutzerdefinierte Envoy-Variablen werden unterstützt.

Dieses Argument kann mehrmals wiederholt werden, um mehrere Header anzugeben. Beispiel:
--add_response_header=key1=value1
--add_response_header=key2=value2
.

--append_response_header

Einen HTTP-Header an die Antwort anfügen, bevor sie an den nachgelagerten Client gesendet wird. Wenn der Header bereits in der Antwort enthalten ist, wird der neue angehängt.

Benutzerdefinierte Envoy-Variablen werden unterstützt.

Dieses Argument kann mehrmals wiederholt werden, um mehrere Header anzugeben. Beispiel:
--append_response_header=key1=value1
--append_response_header=key2=value2
.

Sicherheitsoptionen

Verwenden Sie diese Flags, um die von ESPv2 zugelassenen Anfragen weiter einzugrenzen.

Flag Beschreibung
--underscores_in_headers

Header-Namen, die Unterstriche enthalten, zulassen. Die Standardeinstellung ist false.

Der Unterstrich ist in Headernamen von RFC-7230 zulässig. Dieses Verhalten wird jedoch als Sicherheitsmaßnahme implementiert, da einige Systeme _ und - als austauschbar behandeln.

--envoy_connection_buffer_limit_bytes

Konfigurieren Sie die maximale Datenmenge, die pro Anfrage-/Antworttext zwischengespeichert wird, in Byte. Wird nichts anderes festgelegt, so gilt der Standardwert von Envoy. Weitere Informationen finden Sie unter Envoy-Listener-Konfiguration.

--disable_normalize_path

Deaktivieren Sie die Normalisierung des HTTP-Headers path gemäß RFC 3986. Wir empfehlen, diese Option aktiviert zu lassen, wenn Ihr Backend die Pfadnormalisierung standardmäßig ausführt.

Folgende Tabelle enthält Beispiele für den Anfrage-path, der das Backend basierend auf der Konfiguration dieses Flags von ESPv2 empfängt.


        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------
     

Standardmäßig normalisiert ESPv2 Pfade. Deaktivieren Sie die Funktion nur, wenn Ihr Traffic von diesem Verhalten betroffen ist.

Hinweis: Gemäß RFC 3986 hebt diese Option die Maskierung prozent-codierte Schrägstriche nicht auf. Informationen zum Aktivieren dieses nicht konformen Verhaltens finden Sie im --disallow_escaped_slashes_in_path-Flag.

Hinweis: Die Case-Normalisierung aus RFC 3986 wird nicht unterstützt, auch wenn diese Option aktiviert ist.

Weitere Informationen finden Sie unter Informationen zu Pfadvorlagen.

--disable_merge_slashes_in_path

Deaktivieren Sie die Zusammenführung benachbarter Schrägstriche im HTTP-Header path. Wir empfehlen, diese Option aktiviert zu lassen, wenn Ihr Backend standardmäßig die Zusammenführung nutzt.

Folgende Tabelle enthält Beispiele für den Anfrage-path, der das Backend basierend auf der Konfiguration dieses Flags von ESPv2 empfängt.


        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------
     

ESPv2 führt Schrägstriche standardmäßig zusammen. Deaktivieren Sie die Funktion nur, wenn Ihr Traffic von diesem Verhalten betroffen ist.

Weitere Informationen finden Sie unter Informationen zu Pfadvorlagen.

--disallow_escaped_slashes_in_path

Lässt Anfragen mit maskierten prozentualen Schrägstrichen nicht zu:

  • %2F oder %2f werden als / behandelt
  • %5C oder %5c werden als \ behandelt

Ist diese Option aktiviert, hängt das Verhalten vom verwendeten Protokoll ab:

  • Für OpenAPI-Back-Ends werden Anfragepfade mit maskierten Schrägstrichen automatisch über eine Weiterleitung entfernt.
  • Für gRPC-Back-Ends werden Anfragepfade mit maskierten prozent-codierten Schrägstrichen abgelehnt (gRPC unterstützt keine Weiterleitungen).

Diese Option ist nicht RFC 3986-konform und ist daher standardmäßig deaktiviert. Wenn Ihr Backend nicht RFC 3986-konform ist und Schrägstriche maskiert, müssen Sie diese Option in ESPv2 aktivieren. Dadurch werden Angriffe auf den Pfad verhindert, die dazu führen, dass Sicherheitsanforderungen nicht erzwungen werden.

Weitere Informationen finden Sie unter Informationen zu Pfadvorlagen.

JWT-Authentifizierung

Mit diesen Flags können Sie ESPv2 so konfigurieren, dass remote Jwks mit Wiederholungsversuchen abgerufen werden.

Flag Beschreibung
--jwks_fetch_num_retries

Geben Sie die Anzahl der Wiederholungen in der Remote-JWKS-Abrufrichtlinie an. Der Standardwert ist 0, nicht wiederholen.

--jwks_fetch_retry_back_off_base_interval_ms

Geben Sie das exponentielle Backoff des Intervalls für JWKS-Abrufe in Millisekunden an. Der Standardwert ist 200 ms, wenn nicht anders festgelegt.

--jwks_fetch_retry_back_off_max_interval_ms

Geben Sie das maximale exponentielle Backoff-Intervall für JWKS-Abrufwiederholungen in Millisekunden an. Der Standardwert ist 32, wenn nicht anders festgelegt.

--jwks_cache_duration_in_s

Geben Sie die Cache-Dauer des öffentlichen JWT-Schlüssels in Sekunden an. Der Standardwert beträgt 5 Minuten, wenn er nicht festgelegt wird.

--jwks_async_fetch_fast_listener

Nur anwendbar, wenn das Flag --disable_jwks_async_fetch nicht festgelegt ist. Dieses Flag bestimmt, ob ESPv2 wartet, bis der erste jwks-Abruf abgeschlossen ist, bevor der Listener-Port gebunden wird. Bei „false“ wird gewartet. Der Standardwert ist "false".

--jwt_cache_size

Geben Sie die Anzahl der eindeutigen JWT-Tokens als maximale JWT-Cache-Größe an. Im Cache werden nur verifizierte Tokens gespeichert. Bei 0 ist der JWT-Cache deaktiviert. Dieses Flag begrenzt die Arbeitsspeichernutzung für den JWT-Cache. Der im Cache verwendete Arbeitsspeicher beträgt ungefähr (Tokengröße + 64 Byte) pro Token. Wenn keine Angabe erfolgt, wird der Standardwert 100000 verwendet.

--disable_jwt_audience_service_name_check

Normalerweise wird das JWT-Feld aud mit den im OpenAPI-Feld x-google-audiences angegebenen Zielgruppen verglichen. Dieses Flag ändert das Verhalten, wenn das Feld x-google-audiences nicht angegeben ist. Wenn das Feld x-google-audiences nicht angegeben und dieses Flag nicht verwendet wird, wird der Dienstname verwendet, um das JWT-Feld aud zu prüfen. Bei Verwendung dieses Flags wird das Feld aud im JWT nicht geprüft.

Nächste Schritte

Erfahren Sie mehr über: