Le intestazioni di richiesta e risposta personalizzate ti consentono di specificare il bilanciatore del carico può aggiungere richieste e risposte HTTP(S). A seconda delle informazioni rilevate dall'equilibratore del carico, queste intestazioni possono includere le seguenti informazioni:
- Latenza del 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 response sono supportate per i servizi e i bucket di backend.
Per impostazione predefinita, il bilanciatore del carico aggiunge determinate intestazioni a tutte le richieste e le risposte HTTP(S) che esegue tramite proxy tra i backend e i 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 il bilanciatore del carico inoltra una richiesta al backend, aggiunge intestazioni delle richieste.
Il bilanciatore del carico aggiunge le intestazioni delle richieste personalizzate solo alle richieste del client, non ai probe del controllo di integrità. Se il backend richiede un'intestazione specifica dell'autorizzazione mancante dal pacchetto di controllo di integrità, potrebbe non riuscire.
Il bilanciatore del carico imposta le intestazioni di risposta prima di restituire il valore risposte al cliente.
Per attivare le intestazioni personalizzate, specifica un elenco di intestazioni in una proprietà del servizio di backend o del bucket di backend.
Devi specificare ogni intestazione come stringa header-name:header-value. L'intestazione deve
contiene 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 (secondo il documento RFC 7230).
- Il nome dell'intestazione non deve essere
X-User-IPoCDN-Loop. - Non devono essere utilizzati i seguenti intestazioni hop-by-hop:
Keep-Alive,Transfer-Encoding,TE,Connection,Trailer,Upgrade,Proxy-AuthorizationeProxy-Authenticate. 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-GFEoX-Amz-. - Il nome di un'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 le 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 ai valori forniti dal bilanciatore del carico. Un elenco delle variabili consentite nel valore dell'intestazione è riportato nella sezione successiva.
Lo strumento a riga di comando gcloud ha un flag per specificare
che corrispondono a --custom-request-header. Assicurati di racchiudere il valore
nome e 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 clienti che si trovano a Mountain View, in California, il bilanciatore del carico aggiunge un 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 località e ID dell'istanza cache utilizzati 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 per Cloud CDN.
|
| origin_request_header | Riflette il valore dell'intestazione Origin nella richiesta
per i casi d'uso CORS (condivisione delle risorse tra origini).
|
| client_rtt_msec | Tempo di trasmissione stimato del round trip tra il bilanciatore del carico e il client HTTP(S), in millisecondi. Questa è la modalità andata e ritorno (SRTT) misurato dallo stack TCP del bilanciatore del carico, per RFC 2988. Il RTT appiattito è un algoritmo che gestisce le variazioni e le anomalie che possono verificarsi nelle misurazioni del 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. Nella maggior parte dei paesi questi codici corrispondono
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 sono
derivati dalle suddivisioni definite dallo standard ISO-3166-2.
|
| client_city | Il nome della città da cui ha avuto origine la richiesta, ad esempio
Mountain View per Mountain View, California. Non sono presenti
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 del client, ovvero all'indirizzo penultimo 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 server
il bilanciatore del carico è criptato (utilizzando HTTPS, HTTP/2 o HTTP/3); altrimenti
false.
|
| client_protocol | Il protocollo HTTP utilizzato per la comunicazione tra il client e
con il bilanciatore del carico di rete
passthrough esterno regionale. Uno dei seguenti valori: 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. È 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 definito in RFC 6066), se fornita dal client durante l'handshake TLS o QUIC. Il nome host viene convertito in lettere minuscole e con qualsiasi punto finale rimosso. |
| tls_version | Versione TLS negoziata tra client e bilanciatore del carico durante
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 è 4
esadecimali definiti
IANA
Registro delle suite di crittografia TLS
ad esempio, 009C per TLS_RSA_WITH_AES_128_GCM_SHA256. Questo
è 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. |
Il bilanciatore del carico espande le variabili in stringhe vuote quando non può determinare sui loro 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}se inclusa nell'intestazione di una richiesta
I valori geografici (regioni, suddivisioni e città) sono stime basate su
all'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
le informazioni sulla posizione, Google stima le posizioni dei clienti utilizzando l'IP di origine
delle informazioni sugli indirizzi
contenute nei pacchetti ricevuti dal bilanciatore del carico.
Le intestazioni aggiunte dal bilanciatore del carico sovrascriveranno qualsiasi intestazione esistente hanno lo stesso nome. I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. Quando i nomi delle intestazioni vengono passate 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 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 TLS reciproca
Le seguenti variabili di intestazione aggiuntive sono disponibili se TLS mutuale (mTLS) è configurato su TargetHttpsProxy del bilanciatore del carico.
| Variabile | Descrizione |
|---|---|
| client_cert_present | true se il
client ha fornito un certificato durante l'handshake TLS;
altrimenti, false.
|
| client_cert_chain_verified | true se la catena di certificati client viene verificata in base a un TrustStore configurato; in caso contrario, false.
|
| client_cert_error | Stringhe predefinite che rappresentano le condizioni di errore. Per ulteriori informazioni sulle stringhe di errore, consulta le 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
è impostato su client_cert_serial_number_exceeded_size_limit e
il numero di serie sia impostato su una stringa vuota. |
| client_cert_spiffe_id | Il ID SPIFFE dal campo Subject Alternative Name (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 e 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 con codifica Base64 separato da virgole delle estensioni SAN di tipo DNSName. Il SAN 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 dell'intero campo Issuer del certificato. Se |
| client_cert_subject_dn | Codifica DER con codifica Base64 dell'intero campo Subject del certificato. Se |
| client_cert_leaf | Il certificato client finale per una connessione mTLS stabilita in cui il certificato ha superato la convalida. La codifica del certificato è conforme con RFC 9440. Ciò significa che il certificato DER binario è codificato utilizzando Base64 e delimitato da due due punti. Se |
| client_cert_chain | L'elenco di certificati delimitati da virgole, nell'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 finale. La codifica del certificato è conforme a RFC 9440. Se le dimensioni combinate di |
Configura le 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, svuotamento della connessione). timeout, criteri di sicurezza).
- In Intestazioni delle richieste personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il nome dell'intestazione e il valore dell'intestazione per l'intestazione della richiesta personalizzata.
- Inserisci eventuali intestazioni delle richieste personalizzate aggiuntive.
- Fai clic su Salva.
Per rimuovere un'intestazione di 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 connessioni, 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 di 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 delle richieste, specifica un nome e un valore univoci per l'intestazione
ripetizione della bandiera --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 di 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, vedi Esempi di Terraform per Bilanciatori del carico delle applicazioni esterni globali.
Configurare le 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 connessioni, criteri di sicurezza).
- In Intestazioni delle risposte personalizzate, fai clic su Aggiungi intestazione.
- Inserisci il nome dell'intestazione e il valore dell'intestazione per l'intestazione della risposta personalizzata.
- Inserisci eventuali altre intestazioni delle risposte personalizzate.
- 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, svuotamento della connessione). timeout, criteri di sicurezza).
- Fai clic sulla X accanto al nome dell'intestazione di 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 la classe gcloud compute backend-buckets
create o
Comando 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 di 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
Method: backendBuckets.insert oppure
Method: backendBuckets.update
chiamata API.
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 Bilanciatori del carico delle applicazioni esterni globali.
Imposta intestazioni delle risposte per Cloud Storage
Se devi impostare le intestazioni HTTP nelle risposte da
Cloud Storage, ad esempio criteri delle risorse multiorigine,
Intestazioni X-Frame-Options o X-XSS-Protection: Google Cloud offre
utilizzare le intestazioni personalizzate per Cloud CDN
di archiviazione ideale in Cloud Storage. Puoi farlo configurando 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 solo alle risposte 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
Quando configuri un criterio di sicurezza di Google Cloud Armor, puoi configurare Google Cloud Armor per inserire un'intestazione e un valore personalizzati. Se le tue Il criterio di sicurezza di Google Cloud Armor è configurato in modo da inserire lo stesso come nome del bilanciatore del carico delle applicazioni esterno globale o del bilanciatore del carico delle applicazioni classico intestazioni, il valore dell'intestazione specificato nel criterio di sicurezza di Google Cloud Armor verrà sovrascritto il valore compilato dal bilanciatore del carico. Se non vuoi che il criterio 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:
- La dimensione totale di tutte le intestazioni delle richieste personalizzate (nome e valore combinati, prima dell'espansione della variabile) per ciascun servizio di backend non deve superare gli 8 kB o 16 intestazioni di richiesta.
- La dimensione totale di tutte le intestazioni di risposta personalizzate (nome e valore combinati, prima dell'espansione della variabile) per ogni servizio di backend non deve superare 8 KB o 16 intestazioni di risposta.
Passaggi successivi
- Per un caso d'uso di esempio, consulta Configurazione di un bilanciatore del carico con un di backend.