Esegui la migrazione a Extensible Service Proxy 2

Extensible Service Proxy V2 (ESPv2) è un proxy basato su Envoy che consente a Cloud Endpoints di fornire funzionalità di gestione delle API. ESPv2 sostituisce l'Extensible Service Proxy (ESP) basato su NGINX.

Questo documento descrive come eseguire la migrazione di un deployment dell'API Endpoints esistente da ESP a ESPv2.

Prima di iniziare

Prima di iniziare la migrazione, tieni presente i casi d'uso non supportati e le modifiche alle API che comportano interruzioni descritte di seguito.

Casi d'uso non supportati di ESPv2

• L'ambiente flessibile di App Engine non è supportato

  L'ambiente flessibile di App Engine ha il supporto integrato di Endpoints, abilitato impostando endpoints_api_service nel file app.yaml dell'applicazione. Questa implementazione di Endpoints integrata supporta solo ESP; non è possibile eseguire la migrazione a ESPv2.

  Se vuoi utilizzare ESPv2 con l'ambiente flessibile di App Engine, disattiva endpoints_api_service in app.yaml. Puoi eseguire il deployment di ESPv2 come servizio Cloud Run separato utilizzato per gestire la tua applicazione nell'ambiente flessibile di App Engine. Il deployment funziona nello stesso modo in cui ESPv2 viene utilizzato per supportare l'ambiente standard di App Engine.

• La configurazione NGINX personalizzata non è supportata

  ESPv2 è un proxy basato su Envoy. Non può supportare la configurazione del proxy NGINX personalizzato. Se la configurazione dell'ESP utilizza i flag -n o --nginx_config, l'implementazione potrebbe fare affidamento su una configurazione NGINX personalizzata di cui non è possibile eseguire facilmente la migrazione a ESPv2.

Modifiche che provocano un errore

• Il formato dei dati dell'intestazione X-Endpoint-API-UserInfo è stato modificato. Se la tua applicazione utilizza questa intestazione, deve essere modificata per utilizzare il nuovo formato. Per ulteriori dettagli, consulta Gestire i JWT nel servizio di backend.

• Se per una richiesta è richiesta una chiave API, ESP invia l'intestazione X-Endpoint-API-Project-ID con l'ID progetto del consumatore all'applicazione di backend. ESPv2 utilizza due intestazioni diverse,X-Endpoint-API-Consumer-Type e X-Endpoint-API-Consumer-Number, per inviare i dettagli richiesti. Per ulteriori dettagli su Consumer-Type e Consumer-Number inviati con queste intestazioni, consulta la documentazione di riferimento di Service Infrastructure.

• Il formato del corpo della risposta all'errore HTTP è stato modificato. Quando ESPv2 rifiuta una richiesta HTTP, genera un corpo della risposta di errore in un nuovo formato. Se la tua implementazione utilizza il codice client per elaborare il corpo della risposta JSON dell'errore HTTP, il codice client deve essere aggiornato. Per ulteriori dettagli, consulta Corpo della risposta JSON dell'errore HTTP.

• Sono disponibili nuovi flag di avvio e alcuni flag ESP sono stati ritirati o sostituiti in ESPv2. Consulta Modifiche al flag di avvio tra ESP ed ESPv2.

Eseguire la migrazione delle API Endpoints per utilizzare ESPv2

I passaggi di migrazione necessari per utilizzare ESPv2 con le piattaforme serverless (Cloud Run, funzioni Cloud Run, App Engine) sono diversi da quelli necessari per le piattaforme non serverless (Google Kubernetes Engine, Compute Engine e Kubernetes).

I passaggi di migrazione richiesti per ogni tipo di piattaforma sono descritti di seguito:

Piattaforme non serverless: GKE, Compute Engine, Kubernetes

ESPv2 è un sostituto temporaneo per ESP. Per la maggior parte delle configurazioni, devi solo aggiornare il tag dell'immagine Docker.

Tuttavia, potrebbe essere necessario modificare i flag di avvio se hai configurato ESP con:

• Più di una porta tramite i flag --http_port, http2_port e/o --ssl_port.
• SSL, DNS, Client IP o un altro flag raramente utilizzato.

Per ESPv2 sono disponibili nuovi flag di avvio e alcuni flag ESP sono stati ritirati o sostituiti. Per ulteriori dettagli, consulta Modifiche ai flag di avvio tra ESP ed ESPv2.

GKE e Kubernetes

Per eseguire la migrazione delle configurazioni degli endpoint per GKE e Kubernetes, modifica il tag dell'immagine ESP da :1 a :2 nel file di deployment yaml. Ad esempio:

- 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

Sia ESP che ESPv2 vengono dispiegamento nel contenitore Docker utilizzando il comando docker run. Per eseguire la migrazione di Endpoints per Compute Engine a ESPv2, aggiorna il tag dell'immagine Docker da :1 a :2 nel comando. Ad esempio:

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

Piattaforme serverless (Cloud Run, Cloud Functions, App Engine)

Per le piattaforme serverless, ESPv2 viene di solito implementato come servizio Cloud Run per gestire l'applicazione in esecuzione su Cloud Run, Cloud Function o App Engine. Per eseguire la migrazione di Endpoints a ESPv2, devi creare la configurazione del servizio Endpoints esistente in una nuova immagine Docker ESPv2, quindi eseguire il deployment dell'immagine nel servizio Cloud Run ESPv2.

I passaggi di deployment per ESP e ESPv2 sono identici, ad eccezione dei seguenti dettagli:

• Il tag immagine deve essere modificato da :1 a :2 in ESPv2 quando esegui il deployment di ESPv2 in Cloud Run. Ad esempio:

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

• Lo script gcloud_build_image viene scaricato da una posizione diversa. Utilizza gcr.io/endpoints-release/endpoints-runtime-serverless:2 come immagine di base.

• Una variabile di ambiente viene utilizzata per specificare i flag di avvio. Il nome della variabile per l'ESP è ESP_ARGS. Il nome di ESPv2 è ESPv2_ARGS. Consulta Opzioni di avvio di Extensible Service Proxy V2 per ulteriori informazioni sull'impostazione ESPv2_ARGS e sui flag di avvio disponibili.

Modifiche al flag di avvio tra ESP ed ESPv2

Come per Extensible Service Proxy, puoi specificare i flag di configurazione durante il deployment dei servizi ESPv2. Con il passaggio dall'ESP basato su NGINX all'ESPv2 basato su Envoy, alcuni flag sono stati ritirati o sostituiti e ne sono stati aggiunti di nuovi. Questa sezione utilizza tre tabelle per descrivere le modifiche:

• La Tabella 1 descrive i nuovi flag che sostituiscono quelli non più supportati.
• La Tabella 2 descrive i nuovi flag.
• La tabella 3 descrive gli indicatori ritirati.

Flag sostituiti

Nuovi flag

Flag deprecati

Per ulteriori dettagli sui flag di avvio di ESPv2, consulta Opzioni di avvio di Extensible Service Proxy V2. Ulteriori esempi generici e testo di aiuto per i flag sono disponibili nel repository GitHub.

Posizioni JWT predefinite

Per impostazione predefinita, un JWT viene passato nell'intestazione Authorization (con prefisso "Bearer"), nell'intestazione X-Goog-Iap-Jwt-Assertion o nel parametro di query access_token. Queste località sono supportate sia da ESP che da ESPv2. Puoi anche passare un JWT nell'intestazione Authorization (senza prefisso) quando utilizzi ESP. Tuttavia, questa posizione non è supportata in ESPv2.

Se vuoi continuare a trasmettere i token JWT utilizzando l'intestazione Authorization (senza prefisso) dopo la migrazione a ESPv2, puoi:

• Imposta x-google-jwt-locations nel file openAPI (per gli utenti del backend HTTP):

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

• Imposta Authentication.providers.jwt_locations nel file yaml gRPC (per gli utenti del backend gRPC):

jwt_locations:
- header: Authorization

Gestire i token JWT nel servizio di backend

Quando utilizzi i token JWT per eseguire l'autenticazione, ESPv2 ed ESP inviano il risultato dell'autenticazione nell'intestazione X-Endpoint-API-UserInfo all'API di backend. Ti consigliamo di utilizzare questa intestazione anziché l'intestazione Authorization originale, poiché l'intestazione Authorization originale potrebbe essere modificata nelle piattaforme serverless.

L'intestazione X-Endpoint-API-UserInfo contiene un oggetto JSON codificato in Base64Url. Tuttavia, il formato è stato modificato da ESP a ESPv2.

Per ESPv2, l'intestazione X-Endpoint-API-UserInfo contiene il payload JWT originale, senza alcuna modifica.

In ESP, l'intestazione X-Endpoint-API-UserInfo contiene il payload JWT e alcuni campi specifici aggiunti da ESP. ESP aggiunge i campi id, issuer, email e audiences all'oggetto JSON. Aggiunge anche il campo claims per includere il payload JWT originale.

# 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
   }
}

L'esempio seguente illustra le differenze, tutte decodificate in base64url.

# 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
  }
}

Per saperne di più sull'utilizzo dei token JWT con l'autenticazione, consulta Utilizzo di un metodo personalizzato per autenticare gli utenti e Autenticazione tra servizi.

Formato del corpo della risposta JSON di errore

Se una richiesta HTTP viene rifiutata da ESP o ESPv2, il corpo della risposta contiene un codice di stato e un messaggio di errore in formato JSON. Il formato del corpo della risposta è cambiato in ESPv2, come mostrato negli esempi di seguito:

Il corpo della risposta di errore dell'ESP

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

Il corpo della risposta di errore di ESPv2

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

Esistono due differenze principali:

• In ESPv2, il campo code contiene un codice di stato HTTP anziché il codice di stato RPC trovato in ESP.
• Il corpo della risposta all'errore in ESPv2 non contiene un campo details.

Passaggi successivi

Scopri di più su:

• Opzioni di avvio di Extensible Service Proxy v2
• Estensioni OpenAPI
• Il repository ESPv2 su GitHub