Le intestazioni delle richieste e delle risposte personalizzate 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 delle richieste personalizzate sono supportate per i servizi di backend, mentre le intestazioni delle risposte 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 saperne di più, 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 del 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 della risposta prima di restituire le risposte al client.
Per attivare 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 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-IPoCDN-Loop. - Non devono essere utilizzate le seguenti intestazioni hop-by-hop:
Keep-Alive,Transfer-Encoding,TE,Connection,TrailereUpgrade. In conformità con lo standard RFC 2616, queste intestazioni non vengono archiviate dalle cache né propagate dai proxy di destinazione. - Il nome dell'intestazione non deve iniziare con
X-Google,X-Goog-,X-GFEoX-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 il documento RFC 7230, con forme obsolete non consentite.
- 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. 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 della richiesta, ovvero --custom-request-header. Assicurati di racchiudere il nome 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 di 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
Variabili supportate nei valori di intestazione
Per inserire metadati dinamici 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 relativi 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 della 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
fornito da un backend abilitato per Cloud CDN.
|
origin_request_header |
Riflette il valore dell'intestazione Origin nella richiesta per i casi d'uso di condivisione delle risorse multiorigine (CORS).
|
client_rtt_msec |
Tempo di trasmissione di andata e ritorno stimato tra il bilanciatore del carico e il client HTTP(S), in millisecondi. Questo è il parametro del tempo di round trip (SRTT) uniformato misurato dallo stack TCP del bilanciatore del carico, in base a 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 CLDR Unicode, 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 CLDR Unicode, 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 US-ASCII, numeri, spazi e i seguenti caratteri: !#$%&'*+-.^_`|~.
|
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 proveniente da Mountain View.
|
client_ip_address |
L'indirizzo IP del client. In genere, corrisponde all'indirizzo IP client, ovvero 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); in caso contrario, 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
Di seguito sono riportati i valori possibili:
|
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 è lo stesso dell'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 definito nella RFC 6066), se fornita dal client durante l'handshake TLS o QUIC. Il nome host viene convertito in lettere minuscole e l'eventuale punto finale viene rimosso. |
tls_version |
Versione TLS negoziata tra client e 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 cifrari negoziata durante il TLS handshake. Il valore è composto da quattro cifre esadecimali definite dal registro delle suite di crittografia TLS di 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 |
Fingerprint TLS/SSL JA3 se il client si connette utilizzando HTTPS, HTTP/2 o HTTP/3. |
tls_ja4_fingerprint |
Fingerprint 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
Di seguito sono riportati i valori possibili:
|
asn |
Il numero di sistema autonomo (ASN) associato all'indirizzo IP del client. |
cloud_trace_id |
L'ID traccia estratto (o generato) dall'intestazione della richiesta HTTP. |
hostname |
Il nome host originale specificato dal client nell'intestazione della richiesta HTTP Host.
Il valore viene convertito in lettere minuscole e l'eventuale punto finale viene rimosso.
|
Il bilanciatore del carico espande le variabili in stringhe vuote quando non è in grado di determinare i relativi valori. Ad esempio:
- Variabili di posizione geografica quando la posizione dell'indirizzo IP è sconosciuta
- Parametri TLS quando TLS non è in uso
{origin_request_header}quando la richiesta non include un'intestazioneOrigin- L'intestazione
{cdn_cache_status}quando è inclusa in un'intestazione della richiesta
I valori geografici (regioni, suddivisioni e città) sono stime basate sull'indirizzo IP del client. Di tanto in tanto, Google aggiorna i dati che forniscono questi valori per migliorare l'accuratezza e riflettere i cambiamenti geografici e politici. Anche se l'intestazione X-Forwarded-For originale contiene dati sulla posizione validi, Google stima le posizioni dei client utilizzando i dati sull'indirizzo IP di origine contenuti nei pacchetti ricevuti dal bilanciatore del carico.
Le intestazioni aggiunte dal bilanciatore del carico sovrascrivono le intestazioni esistenti con 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 li codifica in minuscolo.
Nei valori di intestazione, gli spazi vuoti iniziali e finali non sono significativi e non vengono passati al backend. Per consentire le parentesi graffe nei valori dell'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 una singola parentesi graffa di chiusura (}).
Intestazioni personalizzate mutual TLS
Le seguenti variabili di intestazione aggiuntive sono disponibili se il mutual TLS (mTLS) è configurato sul TargetHttpsProxy del bilanciatore del carico.
| Variabile | Descrizione |
|---|---|
client_cert_present |
true se il client ha fornito un certificato durante il TLS handshake; altrimenti, false.
|
client_cert_chain_verified |
true se la catena di certificati client viene verificata rispetto a un TrustStore configurato; in caso contrario, false.
|
client_cert_error |
Stringhe predefinite che rappresentano le condizioni di errore. Per saperne di più sulle stringhe di errore, consulta Modalità di convalida del client mTLS. |
client_cert_sha256_fingerprint |
Impronta 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 dal campo del nome alternativo del soggetto (SAN). Se il valore non è valido o supera i 2048 byte, l'ID SPIFFE viene impostato su una stringa vuota. Se l'ID SPIFFE è più lungo di 2048 byte, |
client_cert_uri_sans |
Elenco separato da virgole codificato in 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 (nel formato di stringa per la 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 (nel formato di stringa per la 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 del campo Subject completo 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 del certificato è conforme a 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 di certificati delimitato da virgole, 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 del certificato è conforme a RFC 9440. Se le dimensioni combinate di |
Configura intestazioni della richiesta personalizzate
Console
Per aggiungere intestazioni della richiesta 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à di sessione, timeout di svuotamento della connessione, policy di sicurezza).
- Nella sezione Intestazioni della richiesta personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il Nome intestazione e il Valore intestazione per l'intestazione della richiesta personalizzata.
- Inserisci eventuali intestazioni della 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à di sessione, timeout di svuotamento della connessione, policy 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 della richiesta 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 della richiesta, specifica un nome e un valore univoci per l'intestazione 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 le intestazioni già presenti nel servizio di backend con le intestazioni della richiesta 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
Invia 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, consulta Esempi di Terraform per i bilanciatori del carico delle applicazioni esterni globali.
Configura 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à di sessione, timeout di svuotamento della connessione, policy di sicurezza).
- Nella sezione Intestazioni della risposta personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il Nome intestazione e il Valore intestazione per l'intestazione della risposta personalizzata.
- Inserisci eventuali intestazioni delle risposte 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à di sessione, timeout di svuotamento della connessione, policy 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 chiamate API seguenti:
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, consulta Esempi di Terraform per i bilanciatori del carico delle applicazioni esterni globali.
Imposta le intestazioni della risposta per Cloud Storage
Se devi impostare intestazioni HTTP sulle risposte di Cloud Storage, ad esempio intestazioni Cross-Origin Resource Policy, X-Frame-Options o X-XSS-Protection,Google Cloud offre l'opzione di utilizzare intestazioni personalizzate per Cloud CDN con Cloud Storage. Per farlo, configura le 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 effettuata direttamente all'API Cloud Storage.
Utilizza intestazioni personalizzate con Google Cloud Armor
Puoi configurare un'intestazione della risposta personalizzata con la variabile {cloud_trace_id} su un servizio di backend per restituire un ID traccia univoco ai client, anche quando una richiesta viene rifiutata da una policy di sicurezza di Cloud Armor. Puoi utilizzare questo ID traccia per cercare la voce di log della richiesta corrispondente in Logging. Per saperne di più, consulta Identifica e correla le richieste bloccate nei log.
Quando configuri una policy di sicurezza di Cloud Armor, puoi anche configurare Cloud Armor in modo che inserisca un'intestazione della richiesta e un valore personalizzati. Se la policy di sicurezza di Cloud Armor è configurata per inserire lo stesso nome di intestazione personalizzata delle intestazioni personalizzate del bilanciatore del carico delle applicazioni esterno globale o del bilanciatore del carico delle applicazioni classico, il valore dell'intestazione specificato nella policy di sicurezza di Cloud Armor viene sovrascritto dal valore compilato dal bilanciatore del carico. Se non vuoi che la policy Cloud Armor venga sovrascritta, assicurati di non utilizzare lo stesso nome.
Limitazioni
Le seguenti limitazioni si applicano alle intestazioni personalizzate utilizzate con i bilanciatori del carico globali:
- La dimensione totale di tutte le intestazioni delle richieste personalizzate (nome e valore combinati, prima dell'espansione delle variabili) per ogni servizio di backend non deve superare gli 8 KB o le 16 intestazioni delle richieste.
- La dimensione totale di tutte le intestazioni della risposta personalizzate (nome e valore combinati, prima dell'espansione delle variabili) per ogni servizio di backend non deve superare gli 8 KB o le 16 intestazioni della risposta.
Passaggi successivi
- Per un esempio di caso d'uso, consulta Configura un bilanciatore del carico con un backend esterno.