Opzioni di avvio di Extensible Service Proxy V2

Extensible Service Proxy V2 (ESPv2) è un proxy basato su Envoy che consente a Cloud Endpoints di fornire funzionalità di gestione delle API. Per configurare ESPv2, puoi specificare i flag di configurazione durante il deployment del servizio ESPv2.

Impostazione dei flag di configurazione

Il metodo per impostare i flag di configurazione ESPv2 varia in base alla piattaforma di deployment, come descritto nelle sezioni seguenti.

VM di Compute Engine

I flag di configurazione ESPv2 per Compute Engine sono specificati nel comando docker run. 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

In questo esempio, --service, --rollout_strategy e --backend sono i flag di configurazione ESPv2.

GKE e Kubernetes

Puoi specificare i flag di configurazione per GKE e Kubernetes nel campo args del file manifest del deployment. Ad esempio:

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 questo esempio, --listener_port, --backend, --service e --rollout_strategy sono i flag di configurazione ESPv2.

Cloud Run per piattaforme serverless

Per specificare le opzioni di avvio di Cloud Run per serverless, utilizza la variabile di ambiente ESPv2_ARGS. La variabile può essere impostata nel comando gcloud run deploy utilizzando l'opzione --set-env-vars.

Ad esempio:

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 questo esempio, --enable_debug è il flag di configurazione ESPv2.

Consulta Cloud Functions per OpenAPI, Cloud Run per OpenAPI o Cloud Run per gRPC per ulteriori informazioni sul comando gcloud run deploy.

Per impostare più argomenti nella variabile di ambiente ESPv2_ARGS, specifica un delimitatore personalizzato e utilizzalo per separare più argomenti. Non utilizzare una virgola come delimitatore. Posiziona il delimitatore personalizzato all'inizio della variabile di ambiente ESPv2_ARGS, circondato da accenti circonflessi.

L'esempio seguente utilizza ++ come delimitatore:

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

Se il flag che stai impostando contiene virgole, devi impostare la variabile di ambiente ESPv2_ARGS nello script gcloud_build_image.

Ad esempio, per aggiungere il flag --cors_allow_methods=PUT,POST,GET:

  • Scarica lo script gcloud_build_image.
  • Modifica gcloud_build_image come mostrato di seguito:
    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
  • Esegui lo script gcloud_build_image per creare l'immagine.

Flag di configurazione ESPv2

I flag di configurazione ESPv2 possono essere raggruppati nelle seguenti categorie:

Ulteriori esempi generici e testo della guida per i flag ESPv2 sono disponibili nel repository GitHub.

Configurazione non serverless

Questi flag sono necessari per eseguire ESPv2 su piattaforme non serverless, come GKE, Compute Engine e Kubernetes. Non possono essere impostate quando viene eseguito il deployment in Cloud Run per piattaforme serverless.

``

Flag Descrizione
--service Imposta il nome del servizio Endpoints.
--version Imposta l'ID di configurazione del servizio Endpoints.
--rollout_strategy Specifica la strategia di implementazione della configurazione del servizio, [fixed|managed]. Il valore predefinito è fixed.
--listener_port Identifica la porta per accettare le connessioni downstream. Supporta le connessioni HTTP/1.x, HTTP/2 e gRPC. Il valore predefinito è 8080.
--backend Specifica l'indirizzo del server delle applicazioni di backend locale. Gli schemi validi sono http, https, grpc e grpcs, se inclusi. Lo schema predefinito è >http.

Logging

Utilizza questi flag per configurare ESPv2 in modo che scriva informazioni aggiuntive nel log Stackdriver.

Flag Descrizione
--log_request_headers

Registra i valori delle intestazioni delle richieste specificate, separati da virgole senza spazi. Ad esempio, imposta questo flag come:

--log_request_headers=foo,bar

Se i valori per le intestazioni "foo" e "bar" sono disponibili nella richiesta, il log di Endpoints contiene:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Registra i valori delle intestazioni delle risposte specificate, separati da virgole senza spazi. Ad esempio, imposta questo flag come:

--log_response_headers=baz,bing

Se i valori per le intestazioni "baz" e "bing" sono disponibili nella risposta, il log di Endpoints contiene:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Registra i valori dei campi primitivi del payload JWT specificati, separati da virgole senza spazi. Ad esempio, imposta questo flag come:

--log_jwt_payload=sub,project_id,foo.foo_name

Se i valori sono disponibili nel payload JWT, il log Endpoints contiene:

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

I valori nel payload JWT devono essere campi primitivi (stringa, numero intero). Gli oggetti e gli array JSON non vengono registrati.

--access_log

Se specificato, il percorso del file locale in cui verranno scritte le voci di log degli accessi.

--access_log_format

Formato stringa per specificare il formato del log degli accessi. Se il criterio non viene configurato, viene usata la stringa di formato predefinita. Per informazioni dettagliate sulla grammatica dei formati, consulta la documentazione di riferimento sulle stringhe di formato.

Tracciamento

Utilizza questi flag per configurare i dati di tracciamento ESPv2 inviati a Stackdriver. Questi flag si applicano solo quando il tracciamento è abilitato.

Flag Descrizione
--disable_tracing

Disattiva tracciamento. Il tracciamento è abilitato per impostazione predefinita.

Quando è abilitato, ESPv2 campiona un numero ridotto di richieste alla tua API ogni secondo per ottenere le tracce che invia a Stackdriver Trace. Per impostazione predefinita, viene campionata 1 richiesta su 1000. Utilizza il flag --tracing_sample_rate per modificare la frequenza di campionamento.

--tracing_project_id

L'ID progetto Google per il tracciamento di Stackdriver.

Il tracciamento è un servizio a pagamento. Verrà addebitato un costo per il tracciamento al progetto specificato.

Per impostazione predefinita, viene fatturato l'ID progetto del servizio ESPv2 di cui è stato eseguito il deployment.

L'ID progetto viene determinato chiamando il server dei metadati dell'istanza Google Cloud all'avvio. Se il deployment di ESPv2 viene eseguito al di fuori di Google Cloud (utilizzando il flag --non_gcp), il tracciamento verrà disabilitato automaticamente a meno che questo flag non venga impostato esplicitamente.

--tracing_sample_rate

Impostare la frequenza di campionamento delle tracce su un valore compreso tra 0,0 e 1,0. Questo valore specifica la frazione di richieste campionate.

Il valore predefinito è 0,001, che equivale a 1 su 1000 richieste.

--tracing_incoming_context

Questo flag specifica le intestazioni HTTP da verificare per il contesto della traccia, con i valori dei flag separati da virgole senza spazi. Tieni presente che l'ordine è importante: il contesto della traccia verrà ricavato dalla prima intestazione corrispondente.

I valori possibili sono traceparent, x-cloud-trace-context e grpc-trace-bin.

Se omesse, verranno controllate le intestazioni traceparent e x-cloud-trace-context (in ordine).

Per ulteriori dettagli, consulta Tracciamento dell'API.

--tracing_outgoing_context

Imposta l'intestazione del contesto di traccia nella richiesta inviata al servizio di backend.

Questo flag specifica l'intestazione HTTP da impostare, con i valori dei flag separati da virgole senza spazi.

I valori possibili sono traceparent, x-cloud-trace-context e grpc-trace-bin.

Se omesso, verranno inviate le intestazioni traceparent e x-cloud-trace-context.

Per ulteriori dettagli, consulta Tracciamento dell'API.

Controllo di integrità

Utilizza questi flag per configurare i controlli di integrità per ESPv2. Il primo flag può essere utilizzato per configurare un gestore dell'integrità in modo che risponda alle chiamate di controllo di integrità. Gli altri flag possono essere utilizzati per abilitare il controllo di integrità per il backend gRPC.

/tbody>
Flag Descrizione
-z, --healthz Definire un endpoint per il controllo di integrità. Ad esempio, -z healthz fa sì che ESPv2 restituisca il codice 200 per il percorso /healthz.
--health_check_grpc_backend Abilita ESPv2 per controllare periodicamente il servizio gRPC Health per un backend specificato dal flag --backend. Il backend deve utilizzare il protocollo gRPC e implementare il protocollo per il controllo di integrità gRPC. L'endpoint del controllo di integrità abilitato dal flag --healthz rifletterà il risultato del controllo di integrità del backend.
--health_check_grpc_backend_service Specifica il nome del servizio quando chiami il protocollo di controllo dell'integrità gRPC di backend. Il valore di questo flag viene applicato solo quando viene utilizzato il flag --health_check_grpc_backend. È facoltativo; se non viene configurato, il valore predefinito è vuoto. Un nome di servizio vuoto serve a eseguire una query sullo stato di integrità complessivo del server gRPC.
--health_check_grpc_backend_interval Specifica l'intervallo di controllo e il timeout della richiesta quando chiami il servizio gRPC Health di backend. Il valore di questo flag viene applicato solo quando viene utilizzato il flag --health_check_grpc_backend. Il valore predefinito è 1 secondo. Il formato accettato è una sequenza di numeri decimali, ciascuno con frazione facoltativa e un suffisso di unità, ad esempio "5s", "100ms" o "2m". Le unità di tempo valide sono "m" per i minuti, "s" per i secondi e "ms" per i millisecondi.

Debug

Utilizza questi flag per configurare il debug per ESPv2. Questi flag possono essere utilizzati per configurare una porta di amministrazione Envoy per recuperare configurazione e statistiche o eseguire Envoy in modalità di debug per scrivere informazioni sul livello di debug nel log.

Flag Descrizione
--status_port, --admin_port Abilita l'amministratore di ESPv2 Envoy su questa porta. Per maggiori dettagli, consulta la documentazione di riferimento per l'interfaccia di amministrazione di Envoy. La porta di amministrazione è disabilitata per impostazione predefinita.
--enable_debug Attiva i log a livello di debug e aggiungi intestazioni di debug.

Deployment non Google Cloud

Se il deployment di ESPv2 viene eseguito in un ambiente non Google Cloud, potrebbero essere richiesti i seguenti flag.

Flag Descrizione
--service_account_key

Specifica il file JSON della chiave dell'account di servizio per accedere ai servizi Google. Se l'opzione viene omessa, il proxy contatta il server dei metadati di Google Cloud per recuperare un token di accesso.

--dns_resolver_addresses Gli indirizzi dei resolver DNS. Ogni indirizzo deve essere nel formato IP_ADDR o IP_ADDR:PORT ed essere separato da un punto e virgola (;). Per IP_ADDR, verrà utilizzata la porta DNS predefinita 52. Ad esempio: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) Se il criterio non viene configurato, ESPv2 utilizzerà il resolver predefinito configurato in /etc/resolv.conf
--backend_dns_lookup_family Definisci la famiglia di ricerche DNS per tutti i backend. Le opzioni sono auto, v4only, v6only, v4preferred e all. Il valore predefinito è v4preferred. Tieni presente che auto è un valore precedente. Se imposti il flag su auto, il comportamento sarà equivalente a v6preferred.
--non_gcp Per impostazione predefinita, il proxy tenta di connettersi al server metadati Google Cloud per ottenere la posizione della VM nelle prime richieste. Per saltare questo passaggio, imposta il flag su true.

Test locale

Il deployment di ESPv2 può essere eseguito localmente sulla tua workstation per i test. Per maggiori dettagli, consulta Esecuzione di ESP in locale o su un'altra piattaforma.

Utilizza questi flag insieme ai flag di deployment non Google Cloud per semplificare il deployment locale e i test nell'integrazione continua.

Flag Descrizione
--service_json_path

Specifica un percorso per ESPv2 per caricare la configurazione del servizio endpoint. Con questo flag, ESPv2 utilizzerà una strategia di implementazione "fissa" e i seguenti flag verranno ignorati:

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

Questo flag impedirà a ESPv2 di utilizzare la quota dell'API Service Management.

--enable_backend_address_override

Gli indirizzi di backend possono essere specificati utilizzando il flag --backend o il campo backend.rule.address nella configurazione del servizio. Per gli utenti di OpenAPI, tieni presente che il campo backend.rule.address è impostato dal campo address nell'estensione x-google-backend.

La configurazione del servizio backend.rule.address per operazione viene solitamente specificata per il routing serverless. Per impostazione predefinita, backend.rule.address avrà la priorità sul flag --backend per ogni singola operazione.

Abilita questo flag se vuoi che il flag --backend abbia la priorità. Questa opzione è utile se stai sviluppando su una workstation locale. Quindi puoi utilizzare la stessa configurazione del servizio di produzione, ma sostituire l'indirizzo di backend tramite il flag --backend per i test locali.

Nota: solo l'indirizzo verrà sostituito. Tutti gli altri componenti di backend.rule continueranno a essere applicati (scadenze, autorizzazione di backend, traduzione del percorso e così via).

Estrazione IP client

Utilizza questi flag per configurare l'estrazione degli IP del client per ESPv2.

Flag Descrizione
--envoy_use_remote_address

Configurazione di HttpConnectionManager di Envoy, consulta il riferimento di Envoy per informazioni dettagliate. L'impostazione predefinita è disattivata.

--envoy_xff_num_trusted_hops Configurazione di HttpConnectionManager di Envoy, consulta il riferimento di Envoy per informazioni dettagliate. Il valore predefinito è 2.

Supporto CORS

Consulta la sezione Assistenza CORS per una descrizione delle opzioni di assistenza disponibili. Questa sezione descrive l'utilizzo dei flag di avvio ESPv2 per supportare CORS.

Per abilitare il supporto CORS in ESPv2, includi l'opzione --cors_preset e impostala su uno dei seguenti flag:

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

Se includi --cors_preset=basic o --cors_preset=cors_with_regex, ESPv2:

  • Presuppone che tutti i percorsi di località abbiano lo stesso criterio CORS.
  • Risponde sia a richieste semplici sia a richieste preflight HTTP OPTIONS.
  • Memorizza nella cache il risultato della richiesta OPTIONS preflight per un massimo di 20 giorni (1728000 secondi).
  • Imposta le intestazioni della risposta sui seguenti valori:

    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
    

Per eseguire l'override del valore predefinito di Access-Control-Allow-Origin, specifica una delle seguenti opzioni:

Opzione Description
--cors_allow_origin Utilizzalo con --cors_preset=basic per impostare Access-Control-Allow-Origin su un'origine specifica.
Esempio:
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex Da utilizzare con --cors_preset=cors_with_regex. Consente di utilizzare un'espressione regolare per impostare Access-Control-Allow-Origin.
Esempio:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

L'espressione regolare nell'esempio precedente consente un'origine con http o https e qualsiasi sottodominio di example.com.

Quando imposti questa opzione in un file di configurazione di Kubernetes, devi aggiungere un ulteriore carattere di barra rovesciata per eseguire l'escape di entrambe le istanze di \. nella stringa, ad esempio:

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

Quando imposti questa opzione nello script gcloud_build_image per Cloud Run, cerca di evitare di utilizzare caratteri di escape e barre rovesciate, perché è possibile che non vengano passati correttamente dallo script bash al proxy all'avvio. Usa classi di caratteri anziché metasequenze. Ad esempio: Original: \d Recommended: [0-9]

Dopo aver impostato --cors_preset=basic o --cors_preset=cors_with_regex per abilitare CORS, puoi eseguire l'override dei valori predefiniti delle altre intestazioni della risposta specificando una o più delle seguenti opzioni:

Opzione Description
--cors_allow_methods Imposta Access-Control-Allow-Methods sui metodi HTTP specificati. Specifica i metodi HTTP come stringa con ciascun metodo HTTP separato da una virgola.
Esempio:
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Imposta Access-Control-Allow-Headers sulle intestazioni HTTP specificate. Specifica le intestazioni HTTP come stringa con ogni intestazione HTTP separata da una virgola.
Esempio:
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials Include l'intestazione Access-Control-Allow-Credentials con il valore true nelle risposte. Per impostazione predefinita, l'intestazione Access-Control-Allow-Credentials non è inclusa nelle risposte.
Esempio:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Imposta Access-Control-Expose-Headers sulle intestazioni specificate. Specifica quali intestazioni possono essere mostrate come parte della risposta sotto forma di stringa, con ogni intestazione separata da una virgola.
Esempio:
--cors_preset=basic
--cors_expose_headers=Content-Length
--cors_max_age Imposta Access-Control-Max-Age sulla durata di tempo specificata. Il formato accettabile è una sequenza di numeri decimali, ciascuno con un valore frazionario facoltativo e un suffisso di unità, ad esempio "300m", "1,5h" o "2h45m". Le unità di tempo valide sono "m" per i minuti e "h" per le ore. Se non è impostato, il valore predefinito è "480h".
Esempio:
--cors_preset=basic
--cors_max_age=24h

Supporto TLS

Utilizza questi flag per configurare ESPv2 in modo che utilizzi le connessioni TLS.

Flag Descrizione
--ssl_server_cert_path Percorso del certificato server del proxy. Se configurato, ESPv2 accetta solo connessioni sicure HTTP/1.x e HTTP/2 su listener_port. Richiede i file del certificato e della chiave "server.crt" e "server.key" all'interno di questo percorso.
--ssl_server_cipher_suites Suite di crittografia da utilizzare per le connessioni downstream, specificate come elenco separato da virgole. Consulta la sezione Configurazione della suite di crittografia.
--ssl_backend_client_cert_path Percorso del certificato client del proxy. Se configurato, ESPv2 abilita l'autenticazione reciproca TLS per i backend HTTPS. Richiede i file del certificato e della chiave "client.crt" e "client.key" all'interno di questo percorso.
--ssl_backend_client_root_certs_file Il percorso del file dei certificati radice che ESPv2 utilizza per verificare il certificato del server di backend. Se non specificato, ESPv2 utilizza "/etc/ssl/certs/ca-certificates.crt" per impostazione predefinita.
--ssl_backend_client_cipher_suites Suite di crittografia da utilizzare per i backend HTTPS, specificati come elenco separato da virgole. Consulta la sezione Configurazione della suite di crittografia.
--ssl_minimum_protocol Versione minima del protocollo TLS per la connessione lato client. Fai riferimento a questo
--ssl_maximum_protocol Versione massima del protocollo TLS per la connessione lato client. Fai riferimento a questo
--enable_strict_transport_security Attiva HSTS (HTTP Strict Transport Security). L'intestazione della risposta "Strict-Transport-Security" con valore "max-age=31536000; includeSubdomains;" viene aggiunta a tutte le risposte.
--generate_self_signed_cert Genera un certificato e una chiave autofirmati all'avvio, quindi archiviali in "/tmp/ssl/endpoints/server.crt" e "/tmp/ssl/endpoints/server.key". Ciò è utile quando è necessario solo un certificato di autofirma casuale per gestire le richieste HTTPS. Il certificato generato avrà il nome comune "localhost" e sarà valido per 10 anni.

Timeout e nuovi tentativi

Utilizza questi flag per configurare il timeout delle chiamate HTTP remote e i nuovi tentativi per ESPv2.

Flag Descrizione
--http_request_timeout_s

Imposta il timeout in secondi per le richieste effettuate ai servizi esterni, ad eccezione di Backend e Google Service Control. Include Google ServiceManagement, il server dei metadati e il server IAM di Google. Deve essere > 0 e, se non impostato, il valore predefinito è 30 secondi.

--service_control_network_fail_open

In caso di errori di rete durante la connessione al controllo del servizio Google, le richieste saranno consentite se questo flag è attivo. L'impostazione predefinita è on.

--service_control_check_timeout_ms Imposta il timeout in millisecondi per la richiesta Service Control Check. Deve essere > 0 e il valore predefinito è 1000 se non viene configurato.
--service_control_report_timeout_ms Imposta il timeout in millisecondi per la richiesta di report Service Control. Deve essere > 0 e il valore predefinito è 1000 se non viene configurato.
--service_control_quota_timeout_ms Imposta il timeout in millisecondi per la richiesta di quota di controllo dei servizi. Deve essere > 0. Se non viene configurato, il valore predefinito è 1000.
--service_control_check_retries Imposta il numero di tentativi per la richiesta di controllo del controllo del servizio. Deve essere >= 0 e il valore predefinito è 3 se non è impostato
--service_control_report_retries Imposta il numero di tentativi per la richiesta di report di controllo del servizio. Deve essere >= 0 e il valore predefinito è 5 se non è impostato
--service_control_quota_retries Imposta il numero di tentativi per la richiesta di quota per il controllo dei servizi. Deve essere >= 0 e il valore predefinito è 1 se non è impostato
--backend_retry_ons

Le condizioni in base alle quali ESPv2 esegue un nuovo tentativo sui backend. È possibile specificare una o più condizioni retryOn utilizzando un elenco separato da virgole. Il valore predefinito è reset,connect-failure,refused-stream. Disattiva il nuovo tentativo impostando questo flag su vuoto.

Fai riferimento ai seguenti link per conoscere le condizioni accettate:

--backend_retry_num Il numero consentito di nuovi tentativi. Deve essere >= 0 e il valore predefinito è 1.

Transcodifica gRPC

Utilizza questi flag per configurare ESPv2 per la transcodifica da HTTP/JSON a gRPC.

Flag Descrizione
--transcoding_always_print_primitive_fields

Specifica se stampare i campi primitivi per la transcodifica grpc-json. Per impostazione predefinita, i campi primitivi con valori predefiniti verranno omessi nell'output JSON. Ad esempio, un campo int32 impostato su 0 verrà omesso. L'impostazione di questo flag su true sostituirà il comportamento predefinito e stamperà i campi primitivi indipendentemente dai loro valori. Il valore predefinito è false.

--transcoding_always_print_enums_as_ints

Specifica se stampare le enumerazioni come interi per la transcodifica grpc-json. Per impostazione predefinita, vengono visualizzate come stringhe. Il valore predefinito è false.

--transcoding_stream_newline_delimited

Se true, utilizza il delimitatore di nuova riga per separare i messaggi dei flussi di risposta. Se il valore è false, tutti i messaggi in streaming di risposte vengono transcodificati in un array JSON.

--transcoding_case_insensitive_enum_parsing

Normalmente, i valori enum dei proto devono essere in maiuscolo quando vengono utilizzati in JSON. Imposta questo flag su true se la richiesta JSON utilizza valori enum non in maiuscolo.

--transcoding_preserve_proto_field_names

Specifica se conservare i nomi dei campi proto per la transcodifica grpc-json. Per impostazione predefinita, protobuf genererà i nomi dei campi JSON utilizzando l'opzione json_name o riducendo il testo a cammello, in questo ordine. L'impostazione di questo flag conserverà i nomi dei campi originali. Il valore predefinito è false.

--transcoding_ignore_query_parameters

Un elenco di parametri di ricerca separati da virgole da ignorare per la mappatura dei metodi di transcodifica nella transcodifica grpc-json. Per impostazione predefinita, il filtro del transcodifica non esegue la transcodifica di una richiesta con parametri di ricerca sconosciuti/non validi.

--transcoding_ignore_unknown_query_parameters

Specifica se ignorare parametri di ricerca che non possono essere mappati a un campo protobuf corrispondente nella transcodifica grpc-json. Utilizza questa opzione se non puoi controllare i parametri di ricerca e non li conosci in anticipo. In caso contrario, usa --transcoding_ignore_query_parameters. Il valore predefinito è false.

--transcoding_query_parameters_disable_unescape_plus

Per impostazione predefinita, i segni più "+" nei parametri di ricerca non vengono sottoposti a escape nello spazio " " nella transcodifica grpc-json. In questo modo è possibile supportare HTML 2.0. Se non vuoi farlo, imposta questo flag su true per disattivare la funzionalità.

Modifica di richieste e risposte

Utilizza questi flag per configurare ESPv2 in modo che modifichi parzialmente le richieste e le risposte.

Flag Descrizione
--add_request_header

Aggiungi un'intestazione HTTP alla richiesta prima di inviarla al backend upstream. Se l'intestazione è già presente nella richiesta, il suo valore verrà sostituito con quello nuovo.

Supporta le variabili personalizzate di Envoy.

Questo argomento può essere ripetuto più volte per specificare più intestazioni. Ad esempio:
--add_request_header=key1=value1
--add_request_header=key2=value2
.

--append_request_header

Aggiungi un'intestazione HTTP alla richiesta prima di inviarla al backend a monte. Se l'intestazione è già presente nella richiesta, verrà aggiunto il nuovo valore.

Supporta le variabili personalizzate di Envoy.

Questo argomento può essere ripetuto più volte per specificare più intestazioni. Ad esempio:
--append_request_header=key1=value1
--append_request_header=key2=value2
.

--add_response_header

Aggiungi un'intestazione HTTP alla risposta prima di inviarla al client downstream. Se l'intestazione è già presente nella risposta, verrà sostituita con la nuova.

Supporta le variabili personalizzate di Envoy.

Questo argomento può essere ripetuto più volte per specificare più intestazioni. Ad esempio:
--add_response_header=key1=value1
--add_response_header=key2=value2
.

--append_response_header

Aggiungi un'intestazione HTTP alla risposta prima di inviarla al client downstream. Se l'intestazione è già presente nella risposta, verrà aggiunta la nuova.

Supporta le variabili personalizzate di Envoy.

Questo argomento può essere ripetuto più volte per specificare più intestazioni. Ad esempio:
--append_response_header=key1=value1
--append_response_header=key2=value2
.

Opzioni di sicurezza

Utilizza questi flag per perfezionare ulteriormente le richieste consentite da ESPv2.

Flag Descrizione
--underscores_in_headers

Consente di passare i nomi delle intestazioni contenenti trattini bassi. Il valore predefinito è false.

Il trattino basso è consentito nei nomi delle intestazioni da RFC-7230. Tuttavia, questo comportamento viene implementato come misura di sicurezza perché alcuni sistemi considerano _ e - come intercambiabili.

--envoy_connection_buffer_limit_bytes

Configura la quantità massima di dati che viene memorizzata nel buffer per ogni corpo di richiesta/risposta, in byte. Se non viene configurato, il valore predefinito viene deciso da Envoy. Vedi Configurazione dei listener di Envoy.

--disable_normalize_path

Disabilita la normalizzazione dell'intestazione HTTP path in base allo standard RFC 3986. Ti consigliamo di mantenere questa opzione abilitata se il backend esegue la normalizzazione del percorso per impostazione predefinita.

La tabella seguente fornisce esempi della richiesta path che il backend riceverà da ESPv2 in base alla configurazione di questo flag.


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

Per impostazione predefinita, ESPv2 normalizzerà i percorsi. Disattiva la funzionalità solo se il tuo traffico è interessato da questo comportamento.

Nota: in base alla specifica RFC 3986, questa opzione non consente di eliminare la sequenza di escape con codifica percentuale dei caratteri barra. Vedi il flag --disallow_escaped_slashes_in_path per attivare questo comportamento non conforme.

Nota: la normalizzazione delle maiuscole da RFC 3986 non è supportata, anche se questa opzione è abilitata.

Per ulteriori dettagli, consulta Comprendere i modelli di percorso.

--disable_merge_slashes_in_path

Disattiva l'unione di barre adiacenti nell'intestazione HTTP path. Ti consigliamo di mantenere questa opzione abilitata se il tuo backend esegue l'unione per impostazione predefinita.

La tabella seguente fornisce esempi della richiesta path che il backend riceverà da ESPv2 in base alla configurazione di questo flag.


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

Per impostazione predefinita, ESPv2 unisce le barre. Disattiva la funzionalità solo se il tuo traffico è interessato da questo comportamento.

Per ulteriori dettagli, consulta Comprendere i modelli di percorso.

--disallow_escaped_slashes_in_path

Non consente le richieste con caratteri barra con codifica percentuale di escape:

  • %2F o %2f viene trattato come un /
  • %5C o %5c viene trattato come un \

Quando l'opzione è abilitata, il comportamento dipende dal protocollo utilizzato:

  • Per i backend OpenAPI, i percorsi di richiesta con barre con codifica percentuale di escape verranno automaticamente annullati tramite un reindirizzamento.
  • Per i backend gRPC, i percorsi di richiesta con barre codificate in percentuale con escape verranno rifiutati (gRPC non supporta i reindirizzamenti).

Questa opzione non è conforme a RFC 3986, quindi è disattivata per impostazione predefinita. Se il backend non è compatibile con RFC 3986 ed esegue l'escape delle barre, devi abilitare questa opzione in ESPv2. In questo modo eviterai attacchi di confusione relativa al percorso che comportano la mancata applicazione di requisiti di sicurezza.

Per ulteriori dettagli, consulta Comprendere i modelli di percorso.

Autenticazione JWT

Utilizza questi flag per configurare ESPv2 in modo che recuperi i Jwk remoti con nuovi tentativi.

Flag Descrizione
--jwks_fetch_num_retries

Specifica il numero di nuovi tentativi nel criterio di nuovo recupero JWKS remoto. Il valore predefinito è 0, non riprovare.

--jwks_fetch_retry_back_off_base_interval_ms

Specifica l'intervallo esponenziale di backoff esponenziale per il nuovo tentativo di recupero JWKS, in millisecondi. Il valore predefinito è 200 ms, se non impostato.

--jwks_fetch_retry_back_off_max_interval_ms

Specifica l'intervallo massimo esponenziale del nuovo tentativo di recupero JWKS, in millisecondi. Il valore predefinito è 32 secondi, se non impostato.

--jwks_cache_duration_in_s

Specifica la durata in secondi della cache della chiave pubblica JWT. Il valore predefinito è 5 minuti, se non impostato.

--jwks_async_fetch_fast_listener

Applica solo se non è impostato il flag --disable_jwks_async_fetch. Questo flag determina se ESPv2 attenderà il completamento del recupero jwks iniziale prima di associare la porta del listener. Se il valore è false, l'ordine di risposta verrà aspettato. Il valore predefinito è false.

--jwt_cache_size

Specifica il numero di token JWT univoci come dimensione massima della cache JWT. Nella cache vengono archiviati solo i token verificati. Se pari a 0, la cache JWT è disattivata. Questo flag limita l'utilizzo della memoria per la cache JWT. La memoria della cache utilizzata è approssimativamente (dimensione token + 64 byte) per token. Se non specificato, il valore predefinito è 100.000.

--disable_jwt_audience_service_name_check

Normalmente il campo JWT aud viene verificato in base ai segmenti di pubblico specificati nel campo x-google-audiences OpenAPI. Questo flag modifica il comportamento quando il campo x-google-audiences non è specificato. Se il campo x-google-audiences non è specificato e questo flag non viene utilizzato, il nome del servizio viene usato per controllare il campo JWT aud. Se viene utilizzato questo flag, il campo JWT aud non verrà controllato.

Passaggi successivi

Scopri di più su: