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.

Hinweis

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 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 Migrationsschritte für die Verwendung von ESPv2 mit serverlosen Plattformen (Cloud Run, Cloud Run-Funktionen, 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

Verworfene Flags

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:

• Legen Sie x-google-jwt-locations in Ihrer openAPI-Datei (für HTTP-Backend-Nutzer) fest:

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

• Legen Sie Authentication.providers.jwt_locations in der gRPC-YAML-Datei (für gRPC-Backend-Nutzer) fest:

jwt_locations:
- header: Authorization

JWTs im Back-End-Dienst verarbeiten

Wenn Sie JWTs für die Authentifizierung verwenden, senden ESPv2 und ESP das Authentifizierungsergebnis im Header X-Endpoint-API-UserInfo an die Back-End-API. Wir empfehlen die Verwendung dieses Headers anstelle des ursprünglichen Authorization-Headers, da der ursprüngliche Authorization-Header auf serverlosen Plattformen eventuell angepasst wurde.

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

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

In ESP enthält der Header X-Endpoint-API-UserInfo die JWT-Nutzlast und einige spezifische von ESP hinzugefügte Felder. 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 aufzunehmen.

# 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 Werte wurden mit base64url decodiert.

# This is an example of the original JWT payload:
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2
# extracted from above JWT payload.
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESP
# extracted from above JWT payload.
{
  &quotid&quot:&quot1234567890123456789&quot,
  &quotissuer&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotaudiences&quot: [
    &quotxyz1.example.com&quot
    &quotxyz2.example.com&quot
  ],
  &quotclaims&quot: {
    &quotiss&quot: &quothttps://accounts.google.com&quot,
    &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
    &quotsub&quot: &quot1234567890123456789&quot,
    &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
    &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
    &quotbar&quot: &quotbar.bar.bar.bar&quot,
    &quotazp&quot: &quot98765432109876543210&quot,
    &quotexp&quot: &quot1642809446&quot,
    &quotiat&quot: &quot1642805846&quot
  }
}

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:

• Extensible Service Proxy V2-Startoptionen
• OpenAPI-Erweiterungen
• ESPv2-Repository auf GitHub