Esegui la migrazione a Extensible Service Proxy V2

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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, valuta i casi d'uso non supportati e le modifiche dell'API che provocano errori.

Casi d'uso non supportati da ESPv2

  • L'ambiente flessibile di App Engine non è supportato

    L'ambiente flessibile di App Engine include il supporto integrato degli endpoint che è abilitato impostando endpoints_api_service nel file app.yaml dell'applicazione. L'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 allo stesso modo in cui ESPv2 viene utilizzato per supportare l'ambiente standard di App Engine.

  • La configurazione personalizzata NGINX non è supportata

    ESPv2 è un proxy basato su Envoy. Non supporta la configurazione personalizzata del proxy NGINX. Se la tua configurazione ESP utilizza i flag -n o --nginx_config, la tua implementazione potrebbe affidarsi a 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 è cambiato. Se la tua applicazione utilizza questa intestazione, devi modificarla per utilizzare il nuovo formato. Per ulteriori dettagli, consulta Gestire i JWT nel servizio di backend.

  • Se è necessaria una chiave API per una richiesta, ESP invia l'intestazione X-Endpoint-API-Project-ID con l'ID progetto consumer all'applicazione di backend. ESPv2 utilizza due diverse intestazioni,X-Endpoint-API-Consumer-Type e X-Endpoint-API-Consumer-Number, per inviare i dettagli richiesti. Consulta la documentazione di riferimento per l'infrastruttura di servizio per ulteriori dettagli sui valori di Consumer-Type e Consumer-Number inviati con queste intestazioni.

  • Il formato del corpo della risposta di errore HTTP è stato modificato. Quando ESPv2 rifiuta una richiesta HTTP, viene generato un corpo di risposta di errore in un nuovo formato. Se l'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 il 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 la sezione Modifiche ai flag di avvio tra ESP e ESPv2.

Migrazione delle API Endpoints per l'utilizzo di ESPv2

I passaggi della migrazione necessari per utilizzare ESPv2 con le piattaforme serverless (Cloud Run, Cloud Functions, App Engine) sono diversi dai passaggi richiesti per le piattaforme non server (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 di ESP. Per la maggior parte delle configurazioni, è sufficiente eseguire l'aggiornamento al tag immagine Docker.

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

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

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

GKE e Kubernetes

Per eseguire la migrazione delle configurazioni degli endpoint per GKE e Kubernetes, modifica il tag immagine ESP da :1 a :2 nel file yaml di deployment. 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

Viene eseguito il deployment di ESP e ESPv2 nel container docker utilizzando il comando docker run. Per eseguire la migrazione di Endpoints per Compute Engine a ESPv2, aggiorna il tag 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 sottoposto a deployment come servizio Cloud Run per gestire l'applicazione in esecuzione su Cloud Run, Cloud Function o App Engine. Per eseguire la migrazione degli endpoint 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 di gcloud_build_image viene scaricato da una posizione diversa. Utilizza gcr.io/endpoints-release/endpoints-runtime-serverless:2 come immagine di base.

  • Per specificare i flag di avvio viene utilizzata una variabile di ambiente. Il nome della variabile per ESP è ESP_ARGS. Il nome di ESPv2 è ESPv2_ARGS. Leggi le opzioni di avvio di Extensible Service Proxy V2 per ulteriori informazioni sull'impostazione di ESPv2_ARGS e sui flag di avvio disponibili.

Modifiche ai flag di avvio tra ESP e ESPv2

Come con 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 deprecati o sostituiti e sono stati aggiunti nuovi flag. Questa sezione utilizza tre tabelle per descrivere le modifiche:

  • La Tabella 1 descrive i nuovi flag che sostituiscono quelli ritirati.
  • La Tabella 2 descrive i nuovi flag.
  • La Tabella 3 descrive i flag deprecati.

Flag sostituiti

Nuove segnalazioni Flag sostituiti Descrizione
--listener_port --http_port, --http2_port, --ssl_port Una singola porta del listener Envoy supporta http, http2 e ssl in ESPv2. Non è necessario specificare porte separate.
--ssl_server_cert_path --ssl_port Quando viene utilizzato --ssl_server_cert_path, ESPv2 utilizza i certificati di file server.key e server.crt. Con ESPv2 puoi specificare percorsi di certificato server diversi da /etc/nginx/ssl. Il flag sostituisce --ssl_port in ESP, che utilizza i certificati dei percorsi file /etc/nginx/ssl/nginx.key e /etc/nginx/ssl/nginx.crt.
--ssl_backend_client_cert_path --tls_mutual_auth, --enable_grpc_backend_ssl, --grpc_backend_ssl_private_key_file, --grpc_backend_ssl_cert_chain_file Quando viene utilizzato --ssl_backend_client_cert_path, ESPv2 utilizza i certificati di file client.key e client.crt. Con ESPv2, puoi specificare percorsi di certificati client diversi da /etc/nginx/ssl. Il flag sostituisce --tls_mutual_auth in ESP, che utilizza i certificati dei percorsi file /etc/nginx/ssl/backend.key e /etc/nginx/ssl/backend.crt.
--ssl_backend_client_root_certs_file --grpc_backend_ssl_root_certs_file Con ESPv2, --ssl_backend_client_root_certs_file funziona per tutti i backend. Il flag sostituisce --grpc_backend_ssl_root_certs_file in ESP, che funziona solo per i backend gRPC.
--ssl_minimum_protocol e --ssl_maximum_protocol --ssl_protocols Quando utilizzi --ssl_protocols in ESP, devi elencare tutti i protocolli SSL desiderati. In ESPv2, puoi specificare un protocollo minimo e massimo.
--envoy_use_remote_address e --envoy_xff_num_trusted_hops --xff_trusted_proxy_list, --client_ip_header e --client_ip_position Envoy richiede l'utilizzo di use_remote_address e xff_num_trusted_hops per configurare l'estrazione IP client.
--dns_resolver_addresses --dns Il flag sostitutivo ha lo stesso comportamento, ma un valore predefinito diverso. ESP utilizza 8.8.8.8 come resolver DNS. ESPv2 utilizza il resolver DNS configurato in /etc/resolv.conf.
--service_account_key --non_gcp, --service_account_key In ESP, il flag --service_account_key consente implicitamente il deployment su piattaforme diverse da GCP. Impedisce a ESP di chiamare il server di metadati dell'istanza. In ESPv2, questo comportamento implicito è suddiviso in un altro flag. Durante la migrazione, potresti dover aggiungere --non_gcp, altrimenti ESPv2 non potrà essere avviato su piattaforme diverse da GCP.

Nuove segnalazioni

Nuove segnalazioni Descrizione
--http_request_timeout_s Imposta il timeout per tutte le chiamate remote http/https, ad eccezione delle chiamate di backend e delle chiamate di Google Service Control, in secondi.
--service_control_check_timeout_ms Imposta il timeout, in millisecondi, per le chiamate Google Service Control Check.
--service_control_report_timeout_ms Imposta il timeout per le chiamate Google Service Control Report.
--service_control_quota_timeout_ms Imposta il timeout per le chiamate Quota di controllo di servizio Google.
--service_control_check_retries Specifica il numero di nuovo tentativo per le chiamate Google Service Control Check.
--service_control_report_retries Specifica il numero di nuovi tentativi per le chiamate Google Service Control Report.
--service_control_quota_retries Specifica il numero di nuovi tentativi per le chiamate Google Service Control Quota.
--backend_dns_lookup_family Configurazione specifica di Envoy utilizzata per definire la famiglia di ricerca DNS per tutti i backend.
--disable_tracing Un flag generale utilizzato per disabilitare tutte le tracce.
--tracing_project_id Utilizzato per impostare l'ID del progetto proprietario dei dati di traccia.
--tracing_incoming_context utilizzato per specificare il contesto della traccia in entrata.
--tracing_outgoing_context Utilizzato per specificare il contesto di uscita.

Flag ritirati

Flag ritirati Descrizione
--enable_websocket Websocket è abilitato per impostazione predefinita in Envoy.
--experimental_proxy_backend_host_header Non supportati.
--allow_invalid_headers Non supportati. Questa è una configurazione NGINX: ignore_invalid_headers. Se una richiesta HTTP ha nomi di intestazione non validi, verrà rifiutata da ESPv2. I nomi delle intestazioni validi sono composti da lettere latine, cifre, trattini e possibili trattini bassi. In ESPv2, il flag --underscores_in_headers determina se i trattini bassi sono consentiti nelle intestazioni.
--client_max_body_size Configurazione NGINX, non supportata.
--client_body_buffer_size Configurazione NGINX, non supportata.
--large_client_header_buffers Configurazione NGINX, non supportata.
--keepalive_timeout Configurazione NGINX, non supportata.
--client_body_timeout Configurazione NGINX, non supportata.
--rewrite Non supportati.
--experimental_enable_multiple_api_configs Non supportati.
--enable_backend_routing Non necessario. Il routing di backend è abilitato automaticamente per le piattaforme serverless.
--rollout_fetch_throttle_window_in_s Non necessario.
--nginx_config Non supportati.

Per maggiori dettagli sui flag di avvio ESPv2, consulta le opzioni di avvio di Extensible Service Proxy V2. Ulteriori esempi generici e testo di assistenza per i flag sono disponibili nel repository di GitHub.

Località JWT predefinite

Per impostazione predefinita, un JWT viene trasmesso nell'intestazione Authorization (preceduto da "Bearer"), nell'intestazione X-Goog-Iap-Jwt-Assertion o nel parametro di ricerca access_token. Questi paesi sono supportati sia da ESP sia da ESPv2. Puoi utilizzare un JWT anche nell'intestazione Authorization (senza prefisso) quando usi ESP. Tuttavia, questa località non è supportata nella funzionalità ESPv2.

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

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

jwt_locations:
- header: Authorization

Gestire i JWT nel servizio di backend

Quando utilizzi JWT per eseguire l'autenticazione, ESPv2 e ESP inviano il risultato di autenticazione nell'intestazione X-Endpoint-API-UserInfo all'API di backend. Ti consigliamo di utilizzare questa intestazione anziché l'intestazione Authorization originale, in quanto l'intestazione originale Authorization può essere modificata nelle piattaforme serverless.

L'intestazione X-Endpoint-API-UserInfo contiene un oggetto JSON codificato Base64Url. Tuttavia, il suo 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
   }
}

Il seguente esempio illustra le differenze: tutti sono stati decodificati in base64url.

# This is an example of the original JWT payload:
{
  "iss": "https://accounts.google.com",
  "email": "abcdefg123456@gmail.com",
  "sub": "1234567890123456789",
  "aud": "xyz1.abc.com,xyz2.abc.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.abc.com,xyz2.abc.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.abc.com"
    "xyz2.abc.com"
  ],
  "claims": {
    "iss": "https://accounts.google.com",
    "email": "abcdefg123456@gmail.com",
    "sub": "1234567890123456789",
    "aud": "xyz1.abc.com,xyz2.abc.com",
    "foo": "foo.foo.foo.foo",
    "bar": "bar.bar.bar.bar",
    "azp": "98765432109876543210",
    "exp": "1642809446",
    "iat": "1642805846"
  }
}

Per ulteriori informazioni sull'utilizzo di JWT con autenticazione, consulta le sezioni 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 seguenti:

Il corpo della risposta all'errore di ESP

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

Il corpo della risposta all'errore di ESPv2

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

Le differenze principali sono due:

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

Passaggi successivi

Scopri di più su: