Zu Extensible Service Proxy V2 migrieren

Extensible Service Proxy V2 (ESPv2) ist ein auf Envoy beruhender Proxy, über den Cloud Endpoints Ihnen API-Verwaltungsfeatures zur Verfügung stellen kann. ESPv2 ersetzt den NGINX-basierten Extensible Service Proxy (ESP).

In diesem Dokument wird gezeigt, wie Sie eine vorhandene Endpoints API-Bereitstellung von ESP zu ESPv2 migrieren.

Hinweise

Bevor Sie mit der Migration beginnen, sollten Sie die nicht unterstützten Anwendungsfälle und wichtige API-Änderungen prüfen, die unten beschrieben werden.

Von ESPv2 nicht unterstützte Anwendungsfälle

  • Die flexible App Engine-Umgebung wird nicht unterstützt

    Die flexible App Engine-Umgebung hat eine integrierte Endpoints-Unterstützung, die durch Festlegen von endpoints_api_service in der app.yaml-Datei der Anwendung aktiviert wird. Diese integrierte Endpoints-Implementierung unterstützt nur ESP. Sie kann nicht zu ESPv2 migriert werden.

    Wenn Sie ESPv2 mit der flexiblen App Engine-Umgebung verwenden möchten, deaktivieren Sie endpoints_api_service in app.yaml. Sie können ESPv2 als separaten Cloud Run-Dienst bereitstellen, der zur Verwaltung der Anwendung in der flexiblen App Engine-Umgebung verwendet wird. Die Bereitstellung funktioniert auf die gleiche Weise, dass ESPv2 zur Unterstützung der App Engine-Standardumgebung verwendet wird.

  • Benutzerdefinierte NGINX-Konfiguration wird nicht unterstützt

    ESPv2 ist ein Envoy-basierter Proxy. Eine benutzerdefinierte NGINX-Proxy-Konfiguration wird nicht unterstützt. Wenn Ihre ESP-Konfiguration das Flag -n oder --nginx_config verwendet, liegt Ihrer Implementierung möglicherweise eine benutzerdefinierte NGINX-Konfiguration zugrunde, die nicht so einfach zu ESPv2 migriert werden kann.

Wichtige Änderungen

  • Das Header-Datenformat für X-Endpoint-API-UserInfo wurde geändert. Wenn die Anwendung diesen Header nutzt, muss er angepasst werden, damit das neue Format verwendet werden kann. Weitere Informationen finden Sie unter JWTs im Back-End-Dienst verarbeiten.

  • Wenn für eine Anfrage ein API-Schlüssel erforderlich ist, sendet der ESP den Header X-Endpoint-API-Project-ID mit der Nutzerprojekt-ID an die Back-End-Anwendung. ESPv2 verwendet zwei verschiedene Header, X-Endpoint-API-Consumer-Type und X-Endpoint-API-Consumer-Number, um die erforderlichen Details zu senden. Weitere Informationen zu Consumer-Type und Consumer-Number, die mit diesen Headern gesendet werden, finden Sie in der Referenzdokumentation zu Service Infrastructure.

  • Das Textformat der HTTP-Fehlerantwort wurde geändert. Wenn ESPv2 eine HTTP-Anfrage ablehnt, wird ein Antworttext in einem neuen Format generiert. Wenn Ihre Implementierung Clientcode verwendet, um den JSON-Antworttext des HTTP-Fehlers zu verarbeiten, muss der Clientcode aktualisiert werden. Ausführliche Informationen finden Sie unter JSON-Antworttext des HTTP-Fehlers.

  • Es sind neue Start-Flags verfügbar. Außerdem wurden einige ESP-Flags in ESPv2 eingestellt oder ersetzt. Weitere Informationen finden Sie unter Start-Flag-Änderungen zwischen ESP und ESPv2.

Endpoints APIs zur Verwendung von ESPv2 migrieren

Die erforderlichen Schritte für die Verwendung von ESPv2 mit serverlosen Plattformen (Cloud Run, Cloud Functions, App Engine) unterscheiden sich von den Schritten für nicht serverlose Plattformen (Google Kubernetes Engine, Compute Engine und Kubernetes).

Im Folgenden werden die für jeden Plattformtyp erforderlichen Migrationsschritte beschrieben:

Nicht serverlose Plattformen: GKE, Compute Engine, Kubernetes

ESPv2 ist ein Drop-in-Ersatz für ESP. Bei den meisten Konfigurationen müssen Sie nur das Docker-Image-Tag aktualisieren.

Die Start-Flags müssen jedoch möglicherweise angepasst werden, wenn Sie ESP mit folgendem Befehl konfiguriert haben:

  • Mehr als ein Port mit den Flags --http_port, http2_port und/oder --ssl_port.
  • Die Flags SSL, DNS, Client IP oder ein anderes selten verwendetes Flag.

Für ESPv2 sind neue Start-Flags verfügbar. Außerdem wurden einige ESP-Flags eingestellt oder ersetzt. Weitere Informationen finden Sie unter Start-Flag-Änderungen zwischen ESP und ESPv2.

GKE und Kubernetes

Um Endpoints-Konfigurationen für GKE und Kubernetes zu migrieren, ändern Sie in der Deployment-Datei yaml das ESP-Image-Tag von :1 in :2. Beispiel:

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

Compute Engine

Sowohl ESP als auch ESPv2 werden mit dem Befehl docker run im Docker-Container bereitgestellt. Wenn Sie Endpoints für Compute Engine zu ESPv2 migrieren möchten, aktualisieren Sie im Befehl das Docker-Image-Tag von :1 auf :2. 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

Serverlose Plattformen (Cloud Run, Cloud Functions, App Engine)

Auf serverlosen Plattformen wird ESPv2 als Cloud Run-Dienst bereitgestellt, um Ihre Anwendung zu verwalten, die auf Cloud Run, Cloud Functions oder App Engine ausgeführt wird. Um Endpoints zu ESPv2 zu migrieren, müssen Sie Ihre vorhandene Endpoints-Dienstkonfiguration in einem neuen ESPv2-Docker-Image erstellen und dann das Image in Ihrem Cloud Run-Dienst von ESPv2 bereitstellen.

Die Bereitstellungsschritte für ESP und ESPv2 sind bis auf die folgenden Ausnahmen identisch:

  • Das Image-Tag muss in ESPv2 von :1 zu :2 geändert werden, wenn Sie ESPv2 für Cloud Run bereitstellen. Beispiel:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
--image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
--allow-unauthenticated \
--platform managed \
--project=ESP_PROJECT_ID

  • Das Skript gcloud_build_image wird von einem anderen Speicherort heruntergeladen. Als Basis-Image wird darin gcr.io/endpoints-release/endpoints-runtime-serverless:2 verwendet.

  • Für die Festlegung der Start-Flags wird eine Umgebungsvariable verwendet. Der Variablenname für ESP lautet ESP_ARGS. Der Name für ESPv2 lautet ESPv2_ARGS. Weitere Informationen zum Festlegen von ESPv2_ARGS und den verfügbaren Start-Flags finden Sie unter Startoptionen für Extensible Service Proxy V2.

Änderungen des Start-Flags zwischen ESP und ESPv2

Wie beim Extensible Service Proxy können Sie beim Bereitstellen von ESPv2-Diensten Konfigurations-Flags angeben. Mit der Umstellung von NGINX-basiertem ESP auf Envoy-basiertes ESPv2 wurden einige Flags verworfen oder ersetzt und neue Flags hinzugefügt. In diesem Abschnitt werden die Änderungen in drei Tabellen beschrieben:

  • In Tabelle 1 werden neue Flags beschrieben, die verworfene Flags ersetzen.
  • In Tabelle 2 werden komplett neue Flags beschrieben.
  • In Tabelle 3 werden verworfene Flags beschrieben.

Ersetzte Flags

Neue Flags Ersetzte Flags Beschreibung
--listener_port --http_port, --http2_port, --ssl_port Ein einzelner Envoy-Listener-Port unterstützt HTTP, HTTP2 und SSL in ESPv2. Sie müssen keine separaten Ports angeben.
--ssl_server_cert_path --ssl_port Wenn --ssl_server_cert_path genutzt wird, verwendet ESPv2 Zertifikate aus den Dateien server.key und server.crt. Mit ESPv2 Beta können Sie andere Serverzertifikatpfade als /etc/nginx/ssl angeben. Dieses Flag ersetzt --ssl_port in ESP, das Zertifikate aus den Dateipfaden /etc/nginx/ssl/nginx.key und /etc/nginx/ssl/nginx.crt verwendet.
--ssl_backend_client_cert_path --tls_mutual_auth, --enable_grpc_backend_ssl, --grpc_backend_ssl_private_key_file, --grpc_backend_ssl_cert_chain_file Wenn --ssl_backend_client_cert_path genutzt wird, verwendet ESPv2 Zertifikate aus den Dateien client.key und client.crt. Mit ESPv2 können Sie auch andere Clientzertifikatpfade als /etc/nginx/ssl angeben. Dieses Flag ersetzt --tls_mutual_auth in ESP, das Zertifikate aus den Dateipfaden /etc/nginx/ssl/backend.key und /etc/nginx/ssl/backend.crt verwendet.
--ssl_backend_client_root_certs_file --grpc_backend_ssl_root_certs_file Bei ESPv2 funktioniert --ssl_backend_client_root_certs_file für alle Back-Ends. Dieses Flag ersetzt --grpc_backend_ssl_root_certs_file in ESP, das nur für gRPC-Back-Ends funktioniert.
--ssl_minimum_protocol,--ssl_maximum_protocol --ssl_protocols Wenn Sie --ssl_protocols in ESP verwenden, müssen Sie alle gewünschten SSL-Protokolle auflisten. In ESPv2 können Sie ein Mindest- und ein maximales Protokoll angeben.
--envoy_use_remote_address,--envoy_xff_num_trusted_hops --xff_trusted_proxy_list,--client_ip_header,--client_ip_position Envoy benötigt use_remote_address und xff_num_trusted_hops, um die Extraktion von Client-IP-Adressen zu konfigurieren.
--dns_resolver_addresses --dns Das Ersetzungs-Flag hat die gleiche Funktionsweise, aber einen anderen Standardwert. ESP verwendet 8.8.8.8 als DNS-Resolver. ESPv2 nutzt den in /etc/resolv.conf konfigurierten DNS-Resolver.
--service_account_key --non_gcp, --service_account_key In ESP erlaubt das --service_account_key-Flag implizit das Deployment auf anderen Plattformen als der GCP. Dies verhindert, dass ESP den Instanzmetadatenserver aufruft. In ESPv2 wird das implizite Verhalten in ein anderes Flag unterteilt. Möglicherweise müssen Sie --non_gcp bei der Migration hinzufügen, da ESPv2 andernfalls auf anderen Plattformen als der GCP nicht gestartet werden kann.

Neue Flags

Neue Flags Beschreibung
--http_request_timeout_s Legt das Zeitlimit für alle HTTP-/HTTPS-Remote-Aufrufe mit Ausnahme von Back-End-Aufrufen und Google Service Control-Aufrufen in Sekunden fest.
--service_control_check_timeout_ms Legt das Zeitlimit für Google Service Control Check-Aufrufe in Millisekunden fest.
--service_control_report_timeout_ms Legt das Zeitlimit für Aufrufe von Google Service Control Report fest.
--service_control_quota_timeout_ms Legt das Zeitlimit für Aufrufe von Google Service Control-Kontingenten fest.
--service_control_check_retries Gibt die Wiederholungsnummer für Google Service Control Check-Aufrufe an.
--service_control_report_retries Gibt die Wiederholungsnummer für Aufrufe von Google Service Control Report an.
--service_control_quota_retries Gibt die Wiederholungsnummer für Aufrufe des Google Service Control-Kontingents an.
--backend_dns_lookup_family Envoy-spezifische Konfiguration, die zum Definieren der DNS-Lookup-Familie für alle Back-Ends verwendet wird.
--disable_tracing Ein allgemeines Flag zum Deaktivieren aller Traces.
--tracing_project_id Wird verwendet, um die ID des Projekts festzulegen, zu dem die Trace-Daten gehören.
--tracing_incoming_context wird verwendet, um den eingehenden Trace-Kontext anzugeben.
--tracing_outgoing_context Wird verwendet, um den Kontext für ausgehende Traces anzugeben.

Verworfene Flags

Verworfene Flags Beschreibung
--enable_websocket WebSocket ist in Envoy standardmäßig aktiviert.
--experimental_proxy_backend_host_header Nicht unterstützt.
--allow_invalid_headers Nicht unterstützt. Dies ist eine NGINX-Konfiguration: ignore_invalid_headers. Wenn eine HTTP-Anfrage ungültige Headernamen enthält, wird sie von ESPv2 abgelehnt. Gültige Headernamen bestehen aus Buchstaben, Ziffern, Bindestrichen und eventuell aus Unterstrichen. In ESPv2 gibt das Flag --underscores_in_headers an, ob in Headern Unterstriche zulässig sind.
--client_max_body_size NGINX-Konfiguration, wird nicht unterstützt.
--client_body_buffer_size NGINX-Konfiguration, wird nicht unterstützt.
--large_client_header_buffers NGINX-Konfiguration, wird nicht unterstützt.
--keepalive_timeout NGINX-Konfiguration, wird nicht unterstützt.
--client_body_timeout NGINX-Konfiguration, wird nicht unterstützt.
--rewrite Nicht unterstützt.
--experimental_enable_multiple_api_configs Nicht unterstützt.
--enable_backend_routing Nicht erforderlich. Back-End-Routing ist für serverlose Plattformen automatisch aktiviert.
--rollout_fetch_throttle_window_in_s Nicht erforderlich.
--nginx_config Nicht unterstützt.

Weitere Informationen zu ESPv2-Start-Flags finden Sie unter Startoptionen von Extensible Service Proxy V2. Weitere allgemeine Beispiele und Hilfetexte für Flags erhalten Sie im GitHub-Repository.

JWT-Standardspeicherorte

Standardmäßig wird ein JWT entweder im Header Authorization (mit dem Präfix "Bearer "), im Header X-Goog-Iap-Jwt-Assertion oder im Abfrageparameter access_token übergeben. Diese Standorte werden sowohl vom ESP als auch vom ESPv2 unterstützt. Sie können bei der Verwendung des ESP auch ein JWT im Header Authorization (kein Präfix) übergeben. Dieser Speicherort wird jedoch in ESPv2 nicht unterstützt.

Wenn Sie nach der Migration zu ESPv2 weiterhin JWTs mit dem Header Authorization (kein Präfix) übergeben möchten, haben Sie folgende Möglichkeiten:

x-google-jwt-locations:
- header: "Authorization"

jwt_locations:
- header: Authorization

JWTs im Back-End-Dienst verarbeiten

Wenn zur Authentifizierung JWTs verwendet werden, senden ESPv2 und ESP das Authentifizierungsergebnis im Header X-Endpoint-API-UserInfo an die Back-End-API. Wir empfehlen, diesen Header anstelle des ursprünglichen Authorization-Headers zu verwenden, da der ursprüngliche Authorization-Header auf serverlosen Plattformen geändert werden kann.

Der Header X-Endpoint-API-UserInfo enthält ein Base64Url-codiertes JSON-Objekt. Das Format wurde jedoch von ESP zu ESPv2 geändert.

Bei ESPv2 enthält der Header X-Endpoint-API-UserInfo die ursprüngliche JWT-Nutzlast ohne Änderungen.

Im ESP enthält der Header X-Endpoint-API-UserInfo die JWT-Nutzlast und einige spezifische Felder, die vom ESP hinzugefügt wurden. Der ESP fügt dem JSON-Objekt die Felder id, issuer, email und audiences hinzu. Außerdem wird das Feld claims hinzugefügt, um die ursprüngliche JWT-Nutzlast einzuschließen.

# ESPv1 X-Endpoint-API-UserInfo header value
{
  "id": "extracted from 'sub' field",
  "issuer": "extracted from 'iss' field",
  "email": "extracted from 'email' field",
  # The following "audiences" is extracted from 'aud' field.
  # The 'aud' field may have multiple audiences delimited by coma. e.g. "aud: aud1,aud2".
  # but the following "audiences" is always a JSON array.
  "audiences": ["aud1", "aud2"],
  "claims": {
     Original JWT payload
   }
}

Das folgende Beispiel veranschaulicht die Unterschiede. Alle wurden mit base64url decodiert.

# This is an example of the original JWT payload:
{
  "iss": "https://accounts.google.com",
  "email": "abcdefg123456@gmail.com",
  "sub": "1234567890123456789",
  "aud": "xyz1.example.com,xyz2.example.com",
  "foo": "foo.foo.foo.foo",
  "bar": "bar.bar.bar.bar",
  "azp": "98765432109876543210",
  "exp": "1642809446",
  "iat": "1642805846"
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2
# extracted from above JWT payload.
{
  "iss": "https://accounts.google.com",
  "email": "abcdefg123456@gmail.com",
  "sub": "1234567890123456789",
  "aud": "xyz1.example.com,xyz2.example.com",
  "foo": "foo.foo.foo.foo",
  "bar": "bar.bar.bar.bar",
  "azp": "98765432109876543210",
  "exp": "1642809446",
  "iat": "1642805846"
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESP
# extracted from above JWT payload.
{
  "id":"1234567890123456789",
  "issuer": "https://accounts.google.com",
  "email": "abcdefg123456@gmail.com",
  "audiences": [
    "xyz1.example.com"
    "xyz2.example.com"
  ],
  "claims": {
    "iss": "https://accounts.google.com",
    "email": "abcdefg123456@gmail.com",
    "sub": "1234567890123456789",
    "aud": "xyz1.example.com,xyz2.example.com",
    "foo": "foo.foo.foo.foo",
    "bar": "bar.bar.bar.bar",
    "azp": "98765432109876543210",
    "exp": "1642809446",
    "iat": "1642805846"
  }
}

Weitere Informationen zur Verwendung von JWTs für die Authentifizierung finden Sie unter Benutzerdefinierte Methode zur Authentifizierung von Nutzern und Authentifizierung zwischen Diensten.

Fehler JSON-Antworttextformat

Wenn eine HTTP-Anfrage von ESP oder ESPv2 abgelehnt wird, enthält der Antworttext einen Statuscode und eine Fehlermeldung im JSON-Format. Das Antworttextformat wurde in ESPv2 geändert, wie in den folgenden Beispielen gezeigt:

Der Text der Fehlerantwort von ESP

{
 "code": 5,
 "message": "Method does not exist.",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "service_control"
  }
 ]
}

Der Text der Fehlerantwort von ESPv2

{
 "code": 400,
 "message": "Method does not exist.",
}

Es gibt zwei wesentliche Unterschiede:

  • In ESPv2 enthält das Feld code einen HTTP-Statuscode, also keinen RPC-Statuscode wie in ESP.
  • Der Text der Fehlerantwort in ESPv2 enthält kein details-Feld.

Nächste Schritte

Erfahren Sie mehr über: