Le intestazioni di richieste e risposte personalizzate consentono di specificare ulteriori intestazioni 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 cliente
- Parametri della connessione TLS
Le intestazioni di richiesta personalizzate sono supportate per i servizi di backend, mentre le intestazioni di risposta personalizzate sono supportate per i servizi di backend e i bucket di backend.
Per impostazione predefinita, il bilanciatore del carico aggiunge determinate intestazioni a tutte le richieste e risposte HTTP(S) di cui esegue il proxy tra backend e client. Per ulteriori informazioni, consulta proxy di destinazione.
Prima di iniziare
Se necessario, esegui l'aggiornamento alla versione più recente di Google Cloud CLI:
gcloud components update
Come funzionano le intestazioni personalizzate
Le intestazioni personalizzate funzionano nel seguente modo:
Quando l'Application Load Balancer esterno globale invia una richiesta al backend, il bilanciatore del carico aggiunge le intestazioni delle richieste.
Il bilanciatore del carico delle applicazioni esterno globale imposta le intestazioni delle risposte prima di restituire le risposte al client.
Per abilitare le intestazioni personalizzate, devi specificare un elenco di intestazioni in una proprietà del servizio di backend o del bucket di backend.
Ogni intestazione viene specificata come stringa header-name:header-value. L'intestazione deve contenere i due punti che separano il nome 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 dell'intestazione HTTP (in base al documento RFC 7230).
- Il nome dell'intestazione non deve essere
X-User-IPoCDN-Loop. - Le seguenti intestazioni hop-by-hop non devono essere utilizzate:
Keep-Alive,Transfer-Encoding,TE,Connection,Trailer,Upgrade,Proxy-AuthorizationeProxy-Authenticate. In conformità a RFC 2616, queste intestazioni non vengono archiviate nella cache né propagate dai proxy di destinazione. - Il nome dell'intestazione non deve iniziare con
X-Google,X-Goog-,X-GFEoX-Amz-. - Il nome di un'intestazione non deve comparire più di una volta nell'elenco delle intestazioni aggiunte.
I valori di intestazione devono soddisfare i seguenti requisiti:
- Il valore dell'intestazione deve essere una definizione valida del campo di intestazione HTTP (in base al documento 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 in valori forniti dal bilanciatore del carico. Un elenco di variabili consentite nel valore dell'intestazione si trova nella sezione successiva.
Ad esempio, potresti specificare un'intestazione con due nomi di variabili per la regione e la città del cliente. Lo strumento a riga di comando gcloud include un flag per specificare le intestazioni delle richieste, --custom-request-header. Assicurati di utilizzare solo virgolette dritte (') con questo flag.
Il formato generale del flag è:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
Tutte le variabili devono essere racchiuse tra parentesi graffe. Ad esempio:
--custom-request-header 'X-Client-Geo-Location:{client_region},{client_city}'
Per i clienti che si trovano a Mountain View, in California, il bilanciatore del carico aggiunge un'intestazione come segue:
X-Client-Geo-Location:US,Mountain View
Variabili supportate con i valori di intestazione
Le seguenti variabili possono essere visualizzate nei valori di intestazione personalizzati.
| Variabile | Descrizione |
|---|---|
| cdn_cache_id | Codice di località e ID 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
gestito da un backend abilitato per Cloud CDN.
|
| origin_request_header | Riflette il valore dell'intestazione Origin nella richiesta di 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 del tempo di round trip (SRTT) livellato misurato dallo stack TCP del bilanciatore del carico, secondo il documento RFC 2988. RTT livellato è un algoritmo che si occupa di variazioni e anomalie che possono verificarsi nelle misurazioni RTT. |
| client_region | Il paese (o la regione) associato all'indirizzo IP del cliente. Questo è un codice regione Unicode CLDR, come 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 cliente. Questo è un ID suddivisione CLDR Unicode, come
USCA o CAON. Questi codici Unicode sono
derivati 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 USA-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. È uguale all'indirizzo IP client
che è il penultimo indirizzo nell'intestazione
X-Forwarded-For. |
| client_port | La porta di origine del client. |
| client_encrypted | true se la connessione tra il client e il bilanciatore del carico è criptata (tramite HTTPS, HTTP/2 o HTTP/3); in caso contrario, false.
|
| client_protocol | Il protocollo HTTP utilizzato per la comunicazione tra il client e il bilanciatore del carico. Uno tra HTTP/1.0, HTTP/1.1, HTTP/2 o HTTP/3.
|
| 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. Corrisponde 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 nel documento RFC 6066), se fornita dal client durante l'handshake TLS o QUIC. Il nome host viene convertito in minuscolo e rimosso dal punto finale. |
| tls_version | Versione TLS negoziata tra client e bilanciatore del carico durante l'handshake SSL. I valori possibili sono: 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 è di quattro cifre esadecimali definite dal IANA TLS Cipher Suite Registry, 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 | Fingerprint TLS/SSL JA3 se il client si connette tramite HTTPS, HTTP/2 o HTTP/3. |
Il bilanciatore del carico espande le variabili in stringhe vuote quando non è in grado di determinarne i valori. Ad esempio:
- Variabili di posizione geografica quando la posizione dell'indirizzo IP è sconosciuta
- Parametri TLS quando TLS non è in uso
- Il
{origin_request_header}quando la richiesta non include un'intestazioneOrigin - L'intestazione
{cdn_cache_status}quando è inclusa nell'intestazione di una richiesta
I valori geografici (regioni, suddivisioni e città) sono stime basate sull'indirizzo IP del cliente. Di tanto in tanto, Google aggiorna i dati che forniscono questi valori per migliorare l'accuratezza e riflettere i cambiamenti geografici e politici.
Le intestazioni aggiunte dal bilanciatore del carico sovrascrivono tutte le intestazioni esistenti che hanno lo stesso nome. I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. Quando i nomi delle intestazioni vengono passati a un backend HTTP/2, il protocollo HTTP/2 codifica i nomi delle intestazioni in minuscolo.
Nei valori di intestazione, gli spazi vuoti iniziali e finali non sono significativi e non vengono passati al backend. Per consentire l'utilizzo di parentesi graffe nei valori di intestazione, il bilanciatore del carico interpreta due parentesi graffe di apertura ({{) come una singola parentesi graffa di apertura ({) e due parentesi graffe di chiusura (}}) come un'unica parentesi graffa di chiusura (}).
Intestazioni personalizzate TLS reciproca
Le seguenti variabili di intestazione aggiuntive sono disponibili se sul protocollo TargetHttpsProxy del bilanciatore del carico è configurato TLS reciproco (mTLS).
| Variabile | Descrizione |
|---|---|
| client_cert_present | true se il client ha fornito un certificato durante l'handshake TLS; in caso contrario, false.
|
| client_cert_chain_verified | true se la catena di certificati client è stata verificata in base a un TrustStore configurato; in caso contrario, false.
|
| client_cert_error | Stringhe predefinite che rappresentano le condizioni di errore. Per maggiori informazioni sulle stringhe di errore, consulta l'articolo sulle modalità di convalida del client mTLS. |
| client_cert_sha256_fingerprint | Fingerprint SHA-256 con codifica Base64 del certificato client. |
| client_cert_serial_number | Il numero di serie del certificato client.
Se il numero di serie è più lungo di 50 byte, client_cert_error
viene impostato su client_cert_serial_number_exceeded_size_limit e il
numero di serie viene impostato su una stringa vuota. |
| client_cert_spiffe_id | L'ID SPIFFE del campo SAN (Subject Alternative Name). Se il valore non è valido o supera i 2048 byte, l'ID SPIFFE è impostato su una stringa vuota. Se l'ID SPIFFE è più lungo di 2048 byte, |
| client_cert_uri_sans | Elenco separato da virgole con codifica Base64 delle estensioni SAN di tipo URI.
Le estensioni SAN vengono estratte dal certificato client.
L'ID SPIFFE non è incluso nel campo Se |
| client_cert_dnsname_sans | Elenco separato da virgole con codifica Base64 delle estensioni SAN di tipo DNSName. Le estensioni SAN vengono estratte dal certificato client. Se |
| client_cert_valid_not_before | Timestamp (formato della stringa di data RFC 3339) prima del quale il certificato client non è valido.
Ad esempio, 2022-07-01T18:05:09+00:00.
|
| client_cert_valid_not_after | Timestamp (formato della stringa di data RFC 3339) dopo il quale il certificato client non è valido.
Ad esempio, 2022-07-01T18:05:09+00:00.
|
| client_cert_issuer_dn | Codifica DER con codifica Base64 del campo Issuer completo del certificato. Se |
| client_cert_subject_dn | Codifica DER con codifica Base64 dell'intero campo Oggetto del certificato. Se |
| client_cert_leaf | Il certificato foglia client per una connessione mTLS stabilita in cui il certificato ha superato la convalida. La codifica dei certificati è conforme allo standard RFC 9440. Ciò significa che il certificato DER binario è codificato utilizzando Base64 e delimitato da due punti su entrambi i lati. Se |
| client_cert_chain | L'elenco, delimitato da virgole, di certificati, in ordine TLS standard, della catena di certificati client per una connessione mTLS stabilita in cui il certificato client ha superato la convalida, escluso il certificato foglia. La codifica dei certificati è conforme a RFC 9440. Se la dimensione combinata di |
Configura intestazioni delle richieste personalizzate
Console
Per aggiungere intestazioni delle richieste personalizzate a un servizio di backend esistente:
- Vai alla pagina di riepilogo del bilanciamento del carico.
Vai alla pagina Bilanciamento del carico - Fai clic su Backend.
- Fai clic sul nome di un servizio di backend.
- Fai clic su Modifica .
- Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
- In Intestazioni delle richieste personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il Nome intestazione e il Valore intestazione per l'intestazione della richiesta personalizzata.
- Inserisci eventuali intestazioni di richiesta personalizzate aggiuntive.
- Fai clic su Salva.
Per rimuovere un'intestazione della richiesta personalizzata da un servizio di backend:
- Vai alla pagina di riepilogo del bilanciamento del carico.
Vai alla pagina Bilanciamento del carico - Fai clic su Backend.
- Fai clic sul nome di un servizio di backend.
- Fai clic su Modifica .
- Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
- Fai clic sulla X accanto al nome dell'intestazione della richiesta personalizzata che vuoi rimuovere.
- Fai clic su Salva.
gcloud
Per specificare intestazioni delle richieste personalizzate, utilizza il comando gcloud compute backend-services
create o gcloud compute backend-services
update con il flag --custom-request-header.
Per creare un servizio di backend con intestazioni delle richieste personalizzate:
gcloud compute backend-services create BACKEND_SERVICE_NAME \
--global-health-checks \
--global \
--protocol HTTPS \
--health-checks https-basic-check \
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
Per aggiungere altre intestazioni delle richieste, specifica un nome e un valore di intestazione univoci ripetendo il flag --custom-request-header.
Per aggiungere intestazioni personalizzate a un servizio di backend esistente:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
--custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'
Il passaggio precedente sostituisce tutte le intestazioni già presenti nel servizio di backend con le intestazioni delle richieste specificate nel comando.
Per rimuovere tutte le intestazioni da un servizio di backend:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--no-custom-request-headers
API
Fai una richiesta PATCH al metodo
backendServices.patch:
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME "customRequestHeaders": [ "client_city:Mountain View" ]
Terraform
Per uno script Terraform che crea un bilanciatore del carico con intestazioni personalizzate, vedi Esempi di Terraform per Application Load Balancer esterni globali.
Configurare intestazioni delle risposte personalizzate
Console
Per aggiungere intestazioni delle risposte personalizzate a un servizio di backend esistente:
- Vai alla pagina di riepilogo del bilanciamento del carico.
Vai alla pagina Bilanciamento del carico - Fai clic su Backend.
- Fai clic sul nome di un servizio di backend.
- Fai clic su Modifica .
- Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
- In Intestazioni delle risposte personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il Nome intestazione e il Valore intestazione per l'intestazione della risposta personalizzata.
- Inserisci eventuali intestazioni di risposta personalizzate aggiuntive.
- Fai clic su Salva.
Per rimuovere un'intestazione della risposta personalizzata da un servizio di backend:
- Vai alla pagina di riepilogo del bilanciamento del carico.
Vai alla pagina Bilanciamento del carico - Fai clic su Backend.
- Fai clic sul nome di un servizio di backend.
- Fai clic su Modifica .
- Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
- Fai clic sulla X accanto al nome dell'intestazione della risposta personalizzata che vuoi rimuovere.
- Fai clic su Salva.
gcloud
Per i servizi di backend, utilizza il comando gcloud compute backend-services
create o gcloud compute backend-services
update con il flag --custom-response-header.
Per i bucket di backend, utilizza il comando gcloud compute backend-buckets
create o gcloud compute backend-buckets
update con il flag --custom-response-header.
gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
--custom-response-header='HEADER_NAME:[HEADER_VALUE]'
gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
--custom-response-header='HEADER_NAME:[HEADER_VALUE]'
Esempio con intestazione X-Frame-Options:
gcloud compute backend-buckets update gaming-lab \
--custom-response-header='X-Frame-Options: DENY'
Esempio con intestazione Strict-Transport-Security:
L'esempio seguente mostra come aggiungere un'intestazione della risposta personalizzata per supportare HTTP Strict Transport Security (HSTS):
gcloud compute backend-services update customer-bs-name \
--global \
--custom-response-header='Strict-Transport-Security: max-age=63072000'
API
Per i bucket di backend, utilizza la chiamata API Method: backendBuckets.insert o Method: backendBuckets.update.
Per i servizi di backend, utilizza la chiamata API Method: backendServices.insert o Method: backendServices.update.
Utilizza una delle seguenti chiamate API:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
Aggiungi il seguente snippet al corpo della richiesta JSON:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Terraform
Per uno script Terraform che crea un bilanciatore del carico con intestazioni personalizzate, vedi Esempi di Terraform per Application Load Balancer esterni globali.
Imposta intestazioni di risposta per Cloud Storage
Se devi impostare le intestazioni HTTP nelle risposte di Cloud Storage, ad esempio le intestazioni Cross-Origin Resource Policy, X-Frame-Options o X-XSS-Protection, Google Cloud offre la possibilità di utilizzare intestazioni personalizzate per Cloud CDN con Cloud Storage. Puoi farlo configurando intestazioni personalizzate a livello di bucket di backend del bilanciatore del carico, come descritto in questa pagina.
Le intestazioni delle risposte personalizzate configurate a livello di bucket di backend vengono aggiunte alle risposte solo se la richiesta del client viene inviata all'indirizzo IP del bilanciatore del carico. Le intestazioni personalizzate non vengono aggiunte alle risposte se la richiesta del client è stata inviata direttamente all'API Cloud Storage.
Utilizza intestazioni personalizzate con Google Cloud Armor
Quando configuri un criterio di sicurezza di Google Cloud Armor, puoi configurare Google Cloud Armor in modo da inserire un'intestazione e un valore personalizzati. Se il criterio di sicurezza di Google Cloud Armor è configurato in modo da inserire lo stesso nome di intestazione personalizzato delle intestazioni personalizzate del bilanciatore del carico delle applicazioni esterno globale o del bilanciatore del carico delle applicazioni classico, il valore dell'intestazione specificato nel criterio di sicurezza di Google Cloud Armor viene sovrascritto dal valore compilato dal bilanciatore del carico. Se non vuoi che il criterio di Google Cloud Armor venga sovrascritto, assicurati di non utilizzare lo stesso nome.
Limitazioni
Le seguenti limitazioni si applicano alle intestazioni personalizzate utilizzate con i bilanciatori del carico globali:
- Puoi specificare un massimo di 16 intestazioni di richiesta personalizzate per ogni servizio di backend.
- Puoi specificare un massimo di 16 intestazioni di risposta personalizzate per ogni servizio di backend.
- Le dimensioni totali di tutte le intestazioni delle richieste personalizzate per servizio di backend (nome e valore combinati, prima dell'espansione della variabile) non possono superare gli 8 kB.
- Le dimensioni totali di tutte le intestazioni di risposta personalizzate per servizio di backend (nome e valore combinati, prima dell'espansione della variabile) non possono superare gli 8 kB.
Passaggi successivi
- Per un esempio di caso d'uso, consulta Configurazione di un bilanciatore del carico con un backend esterno.