Opzioni di avvio di Extensible Service Proxy V2

OpenAPI   |  gRPC

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 di ESPv2.

GKE e Kubernetes

Puoi specificare i flag di configurazione per GKE e Kubernetes nel args campo 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 di ESPv2.

Cloud Run per le piattaforme serverless

Per specificare le opzioni di avvio per 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.

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

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, racchiuso tra simboli di attenzione.

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

  Nota: un delimitatore personalizzato viene utilizzato per separare più argomenti.
• Esegui lo script gcloud_build_image per creare l'immagine.

Flag di configurazione di ESPv2

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

• Configurazione non serverless
• Logging
• Tracciamento
• Controllo di integrità
• Debug
• Test locale
• Deployment non Google Cloud
• Estrazione dell'IP del client
• Supporto CORS
• Supporto TLS
• Timeout e ripetizioni
• Transcodifica gRPC
• Modifica di richieste e risposte
• Opzioni di sicurezza
• Autenticazione JWT

Ulteriori esempi generici e testo di aiuto per i flag ESPv2 sono disponibili nel repository GitHub.

Configurazione non serverless

Questi flag sono necessari per eseguire ESPv2 in piattaforme non serverless, come GKE, Compute Engine e Kubernetes. Non possono essere impostati quando vengono eseguiti in Cloud Run per le piattaforme serverless.

Nota: per gli utenti di Kubernetes, NON racchiudere i valori dei campi tra virgolette nei file di configurazione. Ad esempio, --cors_allow_origin="http://example.com" assegnerà il valore di stringa \"http://example.com\" al campo cor_allow_origin anziché al valore di stringa previsto http://example.com.

``

Bandiera	Descrizione
--service	Imposta il nome del servizio Endpoints.
--version	Imposta l'ID 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 di 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 di Stackdriver.

Bandiera	Descrizione
--log_request_headers	Registra i valori delle intestazioni di richiesta specificate, separati da virgole senza spazi. Ad esempio, imposta questo flag come: --log_request_headers=foo,bar Se nella richiesta sono disponibili valori per le intestazioni "foo" e "bar", il log Endpoints contiene: request_headers: foo=foo_value;bar=bar_value
--log_response_headers	Registra i valori delle intestazioni di risposta specificate, separati da virgole senza spazi. Ad esempio, imposta questo flag come: --log_response_headers=baz,bing Se nella risposta sono disponibili i valori per le intestazioni "baz" e "bing", il log 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 degli endpoint 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 del log di accesso.
--access_log_format	Formato di stringa per specificare il formato del log di accesso. Se non viene impostato, viene utilizzata la stringa del formato predefinito. Per la grammatica dettagliata del formato, consulta le informazioni di riferimento sulle stringhe di formato.

Tracciamento

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

Bandiera	Descrizione
--disable_tracing	Disattiva il monitoraggio. Per impostazione predefinita, il monitoraggio è attivo. Se abilitato, ESPv2 esegue il campionamento di un numero ridotto di richieste alla tua API ogni secondo per ottenere le tracce da inviare a Stackdriver Trace. Per impostazione predefinita, viene campionato 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 monitoraggio di Stackdriver. Il monitoraggio è un servizio a pagamento. Al progetto specificato verrà addebitato il costo del monitoraggio. 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 di metadati delle istanze Google Cloud all'avvio. Se ESPv2 viene disegnato al di fuori di Google Cloud (utilizzando il --non_gcp flag), il monitoraggio verrà disattivato automaticamente, a meno che questo flag non sia impostato esplicitamente.
--tracing_sample_rate	Imposta la frequenza di campionamento della traccia su un valore compreso tra 0,0 e 1,0. Questo valore specifica la frazione di richieste campionate. Il valore predefinito è 0,001, ovvero 1 richiesta su 1000.
--tracing_incoming_context	Questo flag specifica quali intestazioni HTTP controllare per il contesto della traccia, con i valori del flag separati da virgole senza spazi. Tieni presente che l'ordine è importante: il contesto della traccia verrà dedotto dalla prima intestazione che corrisponde. I valori possibili includono traceparent, x-cloud-trace-context e grpc-trace-bin. Se omesso, verranno controllate le intestazioni traceparent e x-cloud-trace-context (in ordine). Per ulteriori dettagli, consulta Monitorare l'API.
--tracing_outgoing_context	Imposta l'intestazione del contesto traccia nella richiesta inviata al servizio di backend. Questo flag specifica l'intestazione HTTP da impostare, con i valori del flag separati da virgole senza spazi. I valori possibili includono 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 Monitorare l'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 di integrità che risponda alle chiamate di controllo di integrità. Gli altri flag possono essere utilizzati per attivare il controllo di integrità per il backend gRPC.

/tbody>

Bandiera	Descrizione
-z, --healthz	Definisci un endpoint di controllo di integrità. Ad esempio, -z healthz fa sì che ESPv2 restituisca il codice 200 per il percorso /healthz.
--health_check_grpc_backend	Consenti a ESPv2 di controllare periodicamente il servizio gRPC Health per un backend specificato dal flag --backend. Il backend deve utilizzare il protocollo gRPC e implementare il protocollo di controllo dell'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 di 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 impostato, il valore predefinito è vuoto. Un nome servizio vuoto consente di eseguire 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 di integrità gRPC 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 una 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 di Envoy per recuperare la configurazione e le statistiche o per eseguire Envoy in modalità di debug per scrivere informazioni a livello di debug nel log.

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

Deployment non Google Cloud

Se ESPv2 viene implementato in un ambiente non Google Cloud, potrebbero essere necessari i seguenti flag.

Bandiera	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 di 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 e 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 non impostato, ESPv2 utilizzerà il resolver predefinito configurato in /etc/resolv.conf
--backend_dns_lookup_family	Definisci la famiglia di ricerca 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 di metadati Google Cloud per recuperare la posizione della VM nelle prime richieste. Per saltare questo passaggio, imposta questo flag su true.

Test locale

ESPv2 può essere implementato localmente sulla tua workstation per i test. Per ulteriori 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 e i test locali nell'integrazione continua.

Bandiera	Descrizione
--service_json_path	Specifica un percorso per consentire a ESPv2 di caricare la configurazione del servizio endpoint. Con questo flag, ESPv2 utilizzerà una strategia di implementazione "fissata" e i seguenti flag verranno ignorati: --service --version --rollout_strategy Questo flag impedisce 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 OpenAPI, tieni presente che il campo backend.rule.address viene impostato dal campo address nell'estensione x-google-backend. La configurazione del servizio per operazione backend.rule.address viene solitamente specificata per il routing serverless. Per impostazione predefinita, backend.rule.address avrà la priorità sul flag --backend per ogni singola operazione. Attiva questo flag se vuoi che sia il flag --backend ad avere la priorità. Questa opzione è utile se esegui lo sviluppo su una workstation locale. Poi puoi utilizzare la stessa configurazione del servizio di produzione, ma sostituire l'indirizzo del backend tramite il flag --backend per i test locali. Nota: verrà sostituito solo l'indirizzo. Continueranno a essere applicati tutti gli altri componenti di backend.rule (scadenze, autenticazione di backend, traduzione dei percorsi e così via).

Estrazione dell'IP client

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

Bandiera	Descrizione
--envoy_use_remote_address	Per la configurazione di HttpConnectionManager di Envoy, consulta la documentazione di riferimento di Envoy per informazioni dettagliate. Il valore predefinito è off.
--envoy_xff_num_trusted_hops	Per la configurazione di HttpConnectionManager di Envoy, consulta la documentazione di riferimento di Envoy per informazioni dettagliate. Il valore predefinito è 2.

Supporto CORS

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

Per attivare il supporto CORS in ESPv2, includi l'opzione --cors_preset e imposta uno dei seguenti flag:

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

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

• Si presume che tutti i percorsi delle località abbiano lo stesso criterio CORS.
• Risponde sia alle richieste semplici sia alle richieste di preflight HTTP OPTIONS.
• Memorizza nella cache il risultato della richiesta OPTIONS preflight per un massimo di 20 giorni (1728000 secondi).

• Imposta le intestazioni di 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 sostituire il valore predefinito di Access-Control-Allow-Origin, specifica una delle seguenti opzioni:

Opzione	Descrizione
--cors_allow_origin	Da utilizzare 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	Utilizza 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 Kubernetes, devi aggiungere un carattere barra rovesciata aggiuntivo per eseguire l'escapismo 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 con esegui scambio e barre rovesciate, poiché potrebbero non essere trasmessi correttamente dallo script bash al proxy all'avvio. Utilizza le classi di caratteri anziché le meta sequenze. Ad esempio: Original: \d Recommended: [0-9]

Dopo aver impostato --cors_preset=basic o --cors_preset=cors_with_regex per attivare CORS, puoi sostituire i valori predefiniti delle altre intestazioni di risposta specificando una o più delle seguenti opzioni:

Opzione	Descrizione
--cors_allow_methods	Imposta Access-Control-Allow-Methods sui metodi HTTP specificati. Specifica i metodi HTTP come stringa con ogni 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	Includi 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 esposte nell'ambito della risposta come 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 indicata. Il formato accettato è una sequenza di numeri decimali, ciascuno con un valore frazionario facoltativo e un suffisso di unità, ad esempio "300 m", "1,5 h" o "2 h 45 m". 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.

Bandiera	Descrizione
--ssl_server_cert_path	Percorso del certificato del server proxy. Se configurato, ESPv2 accetta solo connessioni sicure HTTP/1.x e HTTP/2 sulla porta listener_port. Richiede i file del certificato e della chiave "server.crt" e "server.key" in questo percorso.
--ssl_server_cipher_suites	Suite di crittografia da utilizzare per le connessioni a valle, 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 TLS reciproca per i backend HTTPS. Richiede i file della chiave e del certificato "client.crt" e "client.key" all'interno di questo percorso.
--ssl_backend_client_root_certs_file	Il percorso del file dei certificati radice utilizzati da ESPv2 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, specificate 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 questa
--ssl_maximum_protocol	Versione massima del protocollo TLS per la connessione lato client. Fai riferimento a questa
--enable_strict_transport_security	Attiva HSTS (HTTP Strict Transport Security). L'intestazione di risposta "Strict-Transport-Security" con il valore "max-age=31536000; includeSubdomains;" viene aggiunta per tutte le risposte.
--generate_self_signed_cert	Genera un certificato e una chiave autofirmati all'avvio, quindi memorizzali in "/tmp/ssl/endpoints/server.crt" e "/tmp/ssl/endpoints/server.key". Questo è utile quando è necessaria solo una firma autografata casuale per gestire le richieste HTTPS. Il certificato generato avrà il nome comune "localhost" e sarà valido per 10 anni.

Timeout e tentativi di ripetizione

Utilizza questi flag per configurare il timeout e le riatentate delle chiamate HTTP remote per ESPv2.

Bandiera	Descrizione
--http_request_timeout_s	Imposta il timeout in secondi per le richieste effettuate a servizi esterni, ad eccezione di Backend e Google Service Control. Sono inclusi Google ServiceManagement, il server di metadati e il server Google IAM. Deve essere > 0 e il valore predefinito è 30 secondi se non impostato.
--service_control_network_fail_open	In caso di errori di rete durante la connessione al controllo del servizio Google, le richieste verranno consentite se questo flag è attivo. Il valore predefinito è on.
--service_control_check_timeout_ms	Imposta il timeout in millisecondi per la richiesta di controllo del servizio. Deve essere > 0 e il valore predefinito è 1000 se non è impostato.
--service_control_report_timeout_ms	Imposta il timeout in millisecondi per la richiesta di report di controllo del servizio. Deve essere > 0 e il valore predefinito è 1000 se non è impostato.
--service_control_quota_timeout_ms	Imposta il timeout in millisecondi per la richiesta di quota di Service Control. Deve essere > 0 e il valore predefinito è 1000 se non è impostato.
--service_control_check_retries	Imposta i tempi di ripetizione per la richiesta di controllo dei Controlli di servizio. Deve essere >= 0 e il valore predefinito è 3 se non viene impostato
--service_control_report_retries	Imposta i tempi di ripetizione per la richiesta di report di controllo del servizio. Deve essere >= 0 e il valore predefinito è 5 se non viene impostato
--service_control_quota_retries	Imposta i tempi di ripetizione per la richiesta di quota di Service Control. Deve essere >= 0 e il valore predefinito è 1 se non viene impostato
--backend_retry_ons	Le condizioni in cui ESPv2 esegue nuovi tentativi sui backend. È possibile specificare una o più condizioni retryOn utilizzando un elenco separato da virgole. Il valore predefinito è reset,connect-failure,refused-stream. Disattiva la riprova impostando questo flag su vuoto. Per le condizioni accettate, fai riferimento ai seguenti link: x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	Il numero di nuovi tentativi consentiti. Deve essere >= 0 e il valore predefinito è 1.

Transcodifica gRPC

Utilizza questi flag per configurare ESPv2 per la transcodifica di HTTP/JSON in gRPC.

Bandiera	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. Se imposti questo flag su true, il comportamento predefinito verrà ignorato e i campi primitivi verranno stampati indipendentemente dai relativi valori. Il valore predefinito è false.
--transcoding_always_print_enums_as_ints	Specifica se stampare gli enum come interi per la transcodifica di grpc-json. Per impostazione predefinita, vengono visualizzati come stringhe. Il valore predefinito è false.
--transcoding_stream_newline_delimited	Se il valore è true, utilizza il delimitatore di nuova riga per separare i messaggi di streaming della risposta. Se false, tutti i messaggi di streaming della risposta vengono transcodificati in un array JSON.
--transcoding_case_insensitive_enum_parsing	Normalmente, i valori dell'enum proto devono essere in maiuscolo se 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 genera i nomi dei campi JSON utilizzando l'opzione json_name o le lettere maiuscole iniziali, in questo ordine. L'impostazione di questo flag consente di mantenere 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 del metodo di transcodifica nella transcodifica grpc-json. Per impostazione predefinita, il filtro del transcoder non transcodifica 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. Utilizzala se non puoi controllare i parametri di ricerca e non li conosci in anticipo. In caso contrario, utilizza --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 inseriti nello spazio " " nella transcodifica grpc-json. Questo è per supportare HTML 2.0. Se non è richiesta, imposta questo flag su true per disattivare questa funzionalità.

Modifica di richieste e risposte

Utilizza questi flag per configurare ESPv2 in modo da modificare parzialmente richieste e risposte.

Bandiera	Descrizione
--add_request_header	Aggiungi un'intestazione HTTP alla richiesta prima di inviarla al backend a monte. Se l'intestazione è già presente nella richiesta, il relativo valore verrà sostituito con quello nuovo. Supporta le variabili personalizzate 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	Aggiungere un'intestazione HTTP alla richiesta prima di inviarla al backend a monte. Se l'intestazione è già presente nella richiesta, il nuovo valore verrà aggiunto. Supporta le variabili personalizzate 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 a valle. Se l'intestazione è già presente nella risposta, verrà sostituita con quella nuova. Supporta le variabili personalizzate 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 a valle. Se l'intestazione è già presente nella risposta, verrà aggiunta la nuova intestazione. Supporta le variabili personalizzate 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.

Bandiera	Descrizione
--underscores_in_headers	Consenti il passaggio dei nomi di intestazione che contengono trattini bassi. Il valore predefinito è false. Il carattere trattino basso è consentito nei nomi delle intestazioni ai sensi del RFC-7230. Tuttavia, questo comportamento è implementato come misura di sicurezza perché alcuni sistemi trattano _ e - come intercambiabili.
--envoy_connection_buffer_limit_bytes	Configura la quantità massima di dati memorizzati nella cache per ogni corpo della richiesta/risposta, in byte. Se non è impostato, il valore predefinito viene deciso da Envoy. Consulta la configurazione dell'ascoltatore di Envoy.
--disable_normalize_path	Disattiva la normalizzazione dell'intestazione HTTP path in base allo standard RFC 3986. Ti consigliamo di mantenere questa opzione attivata se il tuo backend esegue la normalizzazione dei percorsi 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 normalizza i percorsi. Disattiva la funzionalità solo se il tuo traffico è interessato dal comportamento. Nota: in base a RFC 3986, questa opzione non applica lo scollegamento dei caratteri barra codificati con percentuale. Consulta il flag --disallow_escaped_slashes_in_path per attivare questo comportamento non conforme. Nota: la normalizzazione delle maiuscole dello standard RFC 3986 non è supportata, anche se questa opzione è attivata. Per maggiori dettagli, vedi Informazioni sui modelli di percorso.
--disable_merge_slashes_in_path	Disattiva l'unione di barre oblique adiacenti nell'intestazione HTTP path. Ti consigliamo di mantenere questa opzione attiva 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 dal comportamento. Per maggiori dettagli, vedi Informazioni sui modelli di percorso.
--disallow_escaped_slashes_in_path	Non sono consentite richieste con caratteri barra codificati a percentuale con interpretazione letterale: %2F o %2f viene considerato come / %5C o %5c viene considerato come \ Se è attivata, il comportamento dipende dal protocollo utilizzato: Per i backend OpenAPI, i percorsi di richiesta con barre diagonali con codifica percentuale sfuggita verranno sfuggiti automaticamente tramite un reindirizzamento. Per i backend gRPC, i percorsi delle richieste con barre diagonali con codifica percentuale sfuggita verranno rifiutati (gRPC non supporta i reindirizzamenti). Questa opzione non è conforme a RFC 3986, pertanto è disattivata per impostazione predefinita. Se il tuo backend non è conforme allo standard RFC 3986 ed esegue la fuga delle barre, devi attivare questa opzione in ESPv2. In questo modo, eviterai attacchi di confusione dei percorsi che comportano l'applicazione dei requisiti di sicurezza. Per maggiori dettagli, vedi Informazioni sui modelli di percorso.

Autenticazione JWT

Utilizza questi flag per configurare ESPv2 in modo che recuperi i JWK remoti con i tentativi di recupero.

Bandiera	Descrizione
--jwks_fetch_num_retries	Specifica il numero di tentativi nel criterio per i nuovi tentativi di recupero JWKS remoto. Il valore predefinito è 0, non riprova.
--jwks_fetch_retry_back_off_base_interval_ms	Specifica l'intervallo di base del backoff esponenziale per i tentativi di recupero dei certificati JWKS, in millisecondi. Se non è impostato, il valore predefinito è 200 ms.
--jwks_fetch_retry_back_off_max_interval_ms	Specifica l'intervallo massimo del backoff esponenziale del nuovo tentativo di recupero JWKS, in millisecondi. Se non è impostato, il valore predefinito è 32 secondi.
--jwks_cache_duration_in_s	Specifica la durata della cache della chiave pubblica JWT in secondi. Se non viene impostato, il valore predefinito è 5 minuti.
--jwks_async_fetch_fast_listener	Si applica solo quando il flag --disable_jwks_async_fetch non è impostato. Questo flag determina se ESPv2 attenderà il completamento del recupero inizialejwks prima di associare la porta di ascolto. Se è false, attenderà. Il valore predefinito è false.
--jwt_cache_size	Specifica il numero di token JWT univoci come dimensione massima della cache JWT. La cache memorizza solo i token verificati. Se 0, la cache JWT è disattivata. Questo flag limita l'utilizzo della memoria per la cache JWT. La memoria utilizzata dalla cache è approssimativamente (dimensioni del token + 64 byte) per token. Se non specificato, il valore predefinito è 100000.
--disable_jwt_audience_service_name_check	In genere, il campo JWT aud viene controllato in base ai segmenti di pubblico specificati nel campo aud di OpenAPI.x-google-audiences Questo flag modifica il comportamento quando il campo x-google-audiences non è specificato. Quando il campo x-google-audiences non è specificato e questo flag non viene utilizzato, il nome del servizio viene utilizzato per controllare il campo aud del JWT. Se viene utilizzato questo flag, il campo JWT aud non verrà controllato.

Passaggi successivi

Scopri di più su:

• Eseguire la migrazione a Extensible Service Proxy V2
• Estensioni OpenAPI