Creazione di intestazioni personalizzate nei servizi di backend

Questa pagina descrive come configurare le intestazioni personalizzate nei servizi di backend utilizzati dai bilanciatori del carico delle applicazioni esterni globali.

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 al 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 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 le intestazioni di richiesta.

    Il bilanciatore del carico aggiunge le intestazioni delle richieste personalizzate solo alle richieste del client, non ai probe del controllo di integrità. Se il tuo 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 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 contenere 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).
  • L'intestazione Host può essere configurata, ma è soggetta a determinate limitazioni.
  • Il nome dell'intestazione non deve essere authority. Si tratta di una parola chiave speciale riservata da Google Cloud. Non puoi modificare questa intestazione per i bilanciatori del carico basati su Envoy, come l'Application Load Balancer esterno globale. Ti consigliamo invece di creare altre intestazioni personalizzate in modo da non interferire con i nomi delle intestazioni riservate.
  • Il nome dell'intestazione non deve essere X-User-IP o CDN-Loop.
  • Non devono essere utilizzati i seguenti intestazioni hop-by-hop: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization e Proxy-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-GFE o X-Amz-.
  • Un nome di intestazione non deve comparire 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 le intestazioni della richiesta, ovvero --custom-request-header. Assicurati di racchiudere il nome e il valore dell'intestazione tra virgolette singole diritte (') 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 con sede a Mountain View, in California, il bilanciatore del carico aggiunge un header come segue:

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

Per creare un servizio di backend con intestazioni personalizzate, consulta Configurare le intestazioni delle richieste personalizzate.

Intestazioni host

Quando configuri un'intestazione Host personalizzata con un bilanciatore del carico delle applicazioni esterno globale, si applicano le seguenti limitazioni:

  • Puoi configurare un'intestazione di richiesta Host personalizzata solo se sostituirai un'intestazione di richiesta Host esistente.
  • Non puoi configurare un'intestazione di risposta Host personalizzata utilizzando le azioni di intestazione nella mappa dell'URL. Tuttavia, puoi comunque configurare l'intestazione della risposta Host personalizzata nel servizio di backend.
  • Inoltre, quanto segue si applica sia alle intestazioni di richiesta che a quelle di risposta:
    • Non puoi aggiungere o rimuovere intestazioni Host personalizzate.
    • Non puoi utilizzare le variabili con le intestazioni Host personalizzate.

Variabili supportate con i valori delle intestazioni

Le seguenti variabili possono essere visualizzate nei valori delle intestazioni personalizzate.

Variabile Descrizione
cdn_cache_id Codice posizione e ID dell'istanza della cache utilizzata per soddisfare 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 della condivisione delle risorse tra origini (CORS).
client_rtt_msec Tempo di trasmissione stimato del round trip tra il bilanciatore del carico e il client HTTP(S), in millisecondi. Si tratta del parametro del tempo di circonvoluzione (SRTT) smussato misurato dallo stack TCP del bilanciatore del carico, come indicato nel 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. 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 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 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 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 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 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 minuscolo e viene rimosso eventuali punti finali.
tls_version Versione TLS negoziata tra il client e il bilanciatore del carico durante il 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 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 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 riesce a 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'intestazione Origin
  • L'intestazione {cdn_cache_status} se 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 informazioni sulla posizione valide, Google stima le posizioni dei client utilizzando le informazioni sull'indirizzo IP di origine contenute 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 lettere minuscole.

Nei valori delle intestazioni, gli spazi vuoti iniziali e finali non sono significativi e non vengono trasmessi 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 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 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

Il ID SPIFFE dal campo Nome alternativo dell'oggetto (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_error è impostato su client_cert_spiffe_id_exceeded_size_limit.

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 client_cert_uri_sans.

Se client_cert_uri_sans è più lungo di 512 byte, client_cert_error viene impostato su client_cert_uri_sans_exceeded_size_limit e l'elenco separato da virgole viene impostato su una stringa vuota.

client_cert_dnsname_sans

Elenco delle estensioni SAN di tipo DNSName separate da virgole e codificate in Base64. Le estensioni SAN vengono estratte dal certificato client.

Se client_cert_dnsname_sans è più lungo di 512 byte, client_cert_error viene impostato su client_cert_dnsname_sans_exceeded_size_limit e l'elenco separato da virgole viene impostato su una stringa vuota.

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 Emittente completo del certificato.

Se client_cert_issuer_dn è più lungo di 512 byte, la stringa client_cert_issuer_dn_exceeded_size_limit viene aggiunta a client_cert_error e client_cert_issuer_dn viene impostato su una stringa vuota.

client_cert_subject_dn

Codifica DER con codifica Base64 del campo Oggetto completo del certificato.

Se client_cert_subject_dn è più lungo di 512 byte, la stringa client_cert_subject_dn_exceeded_size_limit viene aggiunta a client_cert_error e client_cert_subject_dn viene impostato su una stringa vuota.

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 a RFC 9440. Ciò significa che il certificato DER binario è codificato utilizzando Base64 e delimitato da due due punti.

Se client_cert_leaf supera i 16 KB non codificati, la stringa client_cert_validated_leaf_exceeded_size_limit viene aggiunta a client_cert_error e client_cert_leaf viene impostato su una stringa vuota.

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 client_cert_leaf e client_cert_chain prima della codifica Base64 superano i 16 KB, la stringa client_cert_validated_chain_exceeded_size_limit viene aggiunta a client_cert_error e client_cert_chain viene impostata su una stringa vuota.

Configura le intestazioni delle richieste personalizzate

Console

Per aggiungere intestazioni delle richieste personalizzate a un servizio di backend esistente:

  1. Vai alla pagina di riepilogo del bilanciamento del carico.
    Vai alla pagina Bilanciamento del carico
  2. Fai clic su Backend.
  3. Fai clic sul nome di un servizio di backend.
  4. Fai clic su Modifica .
  5. Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
  6. In Intestazioni delle richieste personalizzate, fai clic su Aggiungi intestazione.
  7. Inserisci il nome dell'intestazione e il valore dell'intestazione per l'intestazione della richiesta personalizzata.
  8. Inserisci eventuali intestazioni delle richieste personalizzate aggiuntive.
  9. Fai clic su Salva.

Per rimuovere un'intestazione di richiesta personalizzata da un servizio di backend:

  1. Vai alla pagina di riepilogo del bilanciamento del carico.
    Vai alla pagina Bilanciamento del carico
  2. Fai clic su Backend.
  3. Fai clic sul nome di un servizio di backend.
  4. Fai clic su Modifica .
  5. Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
  6. Fai clic sulla X accanto al nome dell'intestazione della richiesta personalizzata che vuoi rimuovere.
  7. 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 di richiesta 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 di richiesta, 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 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"
]

Configurare le intestazioni delle risposte personalizzate

Console

Per aggiungere intestazioni delle risposte personalizzate a un servizio di backend esistente:

  1. Vai alla pagina di riepilogo del bilanciamento del carico.
    Vai alla pagina Bilanciamento del carico
  2. Fai clic su Backend.
  3. Fai clic sul nome di un servizio di backend.
  4. Fai clic su Modifica .
  5. Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
  6. In Intestazioni di risposta personalizzate, fai clic su Aggiungi intestazione.
  7. Inserisci il nome dell'intestazione e il valore dell'intestazione per l'intestazione della risposta personalizzata.
  8. Inserisci eventuali altre intestazioni delle risposte personalizzate.
  9. Fai clic su Salva.

Per rimuovere un'intestazione di risposta personalizzata da un servizio di backend:

  1. Vai alla pagina di riepilogo del bilanciamento del carico.
    Vai alla pagina Bilanciamento del carico
  2. Fai clic su Backend.
  3. Fai clic sul nome di un servizio di backend.
  4. Fai clic su Modifica .
  5. Fai clic su Configurazioni avanzate (affinità sessione, timeout per svuotamento della connessione, criteri di sicurezza).
  6. Fai clic sulla X accanto al nome dell'intestazione di risposta personalizzata che vuoi rimuovere.
  7. 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 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 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]

Impostare le intestazioni di risposta per Cloud Storage

Se devi impostare intestazioni HTTP sulle risposte di Cloud Storage, ad esempio Cross-Origin Resource Policy, intestazioni X-Frame-Options o X-XSS-Protection, Google Cloud offre la possibilità di utilizzare intestazioni personalizzate per Cloud CDN con Cloud Storage. Per farlo, puoi configurare intestazioni personalizzate a livello di bucket del 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 fatta direttamente all'API Cloud Storage.

Utilizzare 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 per inserire lo stesso nome dell'intestazione personalizzata degli intestazioni personalizzate dell'Application Load Balancer esterno globale o dell'Application Load Balancer classico, il valore dell'intestazione specificato nel criterio di sicurezza di Google Cloud Armor viene sovrascritto dal valore inserito dal bilanciatore del carico. Se non vuoi che la regola di Google 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 della richiesta personalizzate (nome e valore combinati, prima dell'espansione della variabile) per ogni servizio di backend non deve superare 8 KB o 16 intestazioni della 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.