Creazione di intestazioni personalizzate nei servizi di backend

Questa pagina descrive come configurare intestazioni personalizzate nei servizi di backend utilizzati dal bilanciatore del carico delle applicazioni classico.

Le intestazioni delle richieste e delle risposte personalizzate ti consentono di specificare intestazioni aggiuntive che il bilanciatore del carico può aggiungere alle richieste e alle risposte HTTP(S). A seconda delle informazioni rilevate dal bilanciatore del carico, queste intestazioni possono includere le seguenti informazioni:

  • Latenza verso il client
  • Posizione geografica dell'indirizzo IP del client
  • Parametri della connessione TLS

Le intestazioni della richiesta personalizzate sono supportate per i servizi di backend, mentre le intestazioni della risposta personalizzate sono supportate per i servizi di backend e i bucket di backend.

Il bilanciatore del carico aggiunge per impostazione predefinita determinate intestazioni a tutte le richieste e risposte HTTP(S) che invia tramite proxy tra backend e client. Per ulteriori informazioni, consulta Proxy di destinazione.

Prima di iniziare

  • Se necessario, esegui l'aggiornamento all'ultima versione di Google Cloud CLI:

    gcloud components update

Come funzionano le intestazioni personalizzate

Le intestazioni personalizzate funzionano nel seguente modo:

  • Quando il bilanciatore del carico inoltra una richiesta al backend, aggiunge le intestazioni della richiesta.

    Il bilanciatore del carico aggiunge intestazioni delle richieste personalizzate solo alle richieste client, non ai probe del controllo di integrità. Se il backend richiede un'intestazione specifica per l'autorizzazione che non è presente nel pacchetto del controllo di integrità, il controllo di integrità potrebbe non riuscire.

  • Il bilanciatore del carico imposta le intestazioni di risposta prima di restituire le risposte al client.

Per abilitare le intestazioni personalizzate, specifica un elenco di intestazioni in una proprietà del servizio di backend o del bucket di backend.

Specifica ogni intestazione come stringa header-name:header-value. L'intestazione deve contenere i due punti che separano il nome dell'intestazione e il valore dell'intestazione.

I nomi delle intestazioni devono soddisfare i seguenti requisiti:

  • Il nome dell'intestazione deve essere una definizione valida del nome del campo di intestazione HTTP (secondo il documento RFC 7230).
  • Il nome dell'intestazione non deve essere X-User-IP o CDN-Loop.
  • Non devono essere utilizzate le seguenti intestazioni hop-by-hop: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer e Upgrade. In conformità con RFC 2616, queste intestazioni non vengono memorizzate dalle cache o propagate dai proxy di destinazione.
  • Il nome dell'intestazione non deve iniziare con X-Google, X-Goog-, X-GFE o X-Amz-.
  • Un nome di intestazione non deve apparire più di una volta nell'elenco delle intestazioni aggiunte.

I valori dell'intestazione devono soddisfare i seguenti requisiti:

  • Il valore dell'intestazione deve essere una definizione valida del campo di intestazione HTTP secondo la RFC 7230, con i moduli obsoleti non consentiti.
  • Il valore dell'intestazione può essere vuoto.
  • Il valore dell'intestazione può includere una o più variabili, racchiuse tra parentesi graffe, che si espandono ai valori forniti dal bilanciatore del carico. Per saperne di più, consulta Variabili supportate nei valori delle intestazioni.

Lo strumento a riga di comando gcloud ha un flag per specificare le intestazioni delle richieste, ovvero --custom-request-header. Assicurati di racchiudere il nome dell'intestazione e il valore dell'intestazione tra virgolette singole dritte (') con questo flag.

Il formato generale del flag è:

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Di seguito è riportato un esempio di valore dell'intestazione con due variabili, client_region e client_city, racchiuse tra parentesi graffe.

    --custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'

Per i client che si trovano a Mountain View, in California, il bilanciatore del carico aggiunge un'intestazione come segue:

X-Client-Geo-Location:US,Mountain View

Per creare un servizio di backend con intestazioni personalizzate, consulta Configura intestazioni della richiesta personalizzate.

Variabili supportate nei valori delle intestazioni

Per inserire metadati dinamici e specifici della richiesta nelle intestazioni personalizzate, puoi utilizzare le seguenti variabili. Quando queste variabili sono racchiuse tra parentesi graffe ({}) all'interno di un valore di intestazione, il bilanciatore del carico le espande ai loro valori in tempo reale, ad esempio la posizione geografica del client, i parametri di connessione o lo stato della cache, prima di passare l'intestazione al backend o al client.

Variabile Descrizione
cdn_cache_id Codice e ID della località dell'istanza della cache utilizzata per gestire la richiesta. Si tratta dello stesso valore inserito nel campo jsonPayload.cacheId dei log delle richieste Cloud CDN in Logging.
cdn_cache_status Stato attuale della cache. I valori possono essere hit, miss, revalidated, stale, uncacheable o disabled per qualsiasi oggetto servito da un backend abilitato a Cloud CDN.
origin_request_header Riflette il valore dell'intestazione Origin nella richiesta per i casi d'uso della condivisione delle risorse tra origini (CORS).
client_rtt_msec Tempo di trasmissione di round trip stimato tra il bilanciatore del carico e il client HTTP(S), in millisecondi. Questo è il parametro tempo di round trip (SRTT) uniforme misurato dallo stack TCP del bilanciatore del carico, in base all'RFC 2988. L'RTT uniformato è un algoritmo che gestisce le variazioni e le anomalie che potrebbero verificarsi nelle misurazioni dell'RTT.
client_region Il paese (o la regione) associato all'indirizzo IP del client. Si tratta di un codice regione Unicode CLDR, ad esempio US o FR. Per la maggior parte dei paesi, questi codici corrispondono direttamente ai codici ISO-3166-2.
client_region_subdivision Suddivisione, ad esempio una provincia o uno stato, del paese associato all'indirizzo IP del client. Si tratta di un ID suddivisione Unicode CLDR, ad esempio USCA o CAON. Questi codici Unicode derivano dalle suddivisioni definite dallo standard ISO-3166-2.
client_city Nome della città da cui ha avuto origine la richiesta, ad esempio, Mountain View per Mountain View, California. Non esiste un elenco canonico di valori validi per questa variabile. I nomi delle città possono contenere lettere, numeri, spazi e i seguenti caratteri US-ASCII: !#$%&'*+-.^_`|~.
client_city_lat_long Latitudine e longitudine della città da cui ha avuto origine la richiesta, ad esempio 37.386051,-122.083851 per una richiesta da Mountain View.
client_ip_address L'indirizzo IP del client. Di solito corrisponde all'indirizzo IP client che è il penultimo indirizzo nell'intestazione X-Forwarded-For, a meno che il client non utilizzi un proxy o l'intestazione X-Forwarded-For non sia stata manomessa.
client_port La porta di origine del client.
client_encrypted true se la connessione tra il client e il bilanciatore del carico è criptata (utilizzando HTTPS, HTTP/2 o HTTP/3); altrimenti, false.
client_protocol Il protocollo HTTP utilizzato per la comunicazione tra il client e il bilanciatore del carico. Uno dei valori tra HTTP/1.0, HTTP/1.1, HTTP/2 o HTTP/3.
device_request_type

Il dispositivo del client, derivato dai valori dell'intestazione User-Agent.

Di seguito sono riportati i valori possibili: DESKTOP, GAME_CONSOLE, GAME_CONSOLE, MOBILE, SET_TOP_BOX, SMART_SPEAKER, SMART_TV, TABLET, UNDETERMINED, WEARABLE.

server_ip_address L'indirizzo IP del bilanciatore del carico a cui si connette il client. Questo può essere utile quando più bilanciatori del carico condividono backend comuni. Questo è uguale all'ultimo indirizzo IP nell'intestazione X-Forwarded-For.
server_port Il numero di porta di destinazione a cui si connette il client.
tls_sni_hostname Indicazione del nome del server (come definita nella RFC 6066), se fornita dal client durante l'handshake TLS o QUIC. Il nome host viene convertito in minuscolo e il punto finale viene rimosso.
tls_version Versione TLS negoziata tra il client e il bilanciatore del carico durante l'handshake SSL. I valori possibili includono: TLSv1, TLSv1.1, TLSv1.2 e TLSv1.3. Se il client si connette utilizzando QUIC anziché TLS, il valore è QUIC.
tls_cipher_suite Suite di crittografia negoziata durante l'handshake TLS. Il valore è costituito da quattro cifre esadecimali definite dal registro delle suite di crittografia TLS IANA, ad esempio 009C per TLS_RSA_WITH_AES_128_GCM_SHA256. Questo valore è vuoto per QUIC e per le connessioni client non criptate.
tls_ja3_fingerprint Impronta TLS/SSL JA3 se il client si connette utilizzando HTTPS, HTTP/2 o HTTP/3.
tls_ja4_fingerprint Impronta TLS/SSL JA4 se il client si connette utilizzando HTTPS, HTTP/2 o HTTP/3.
user_agent_family

Il tipo di browser del client, derivato dai valori dell'intestazione User-Agent.

I valori possibili sono: APPLE, APPLEWEBKIT, BLACKBERRY, DOCOMO, GECKO, GOOGLE, KHTML, KOREAN, MICROSOFT, MSIE, NETFRONT, NOKIA, OBIGO, OPERA, OPENWAVE, OTHER, POLARIS, SEMC, SMIT, TELECA, USER_DEFINED.

asn Il numero di sistema autonomo (ASN) associato all'indirizzo IP del client.