Creazione di intestazioni personalizzate nei servizi di backend

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

Le intestazioni di richiesta e risposta personalizzate ti consentono di specificare il bilanciatore del carico può aggiungere richieste e risposte HTTP(S). In base 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 response sono supportate per i servizi e i bucket di backend.

Il bilanciatore del carico aggiunge alcune intestazioni per impostazione predefinita tutte le richieste e le risposte HTTP(S) che esegue il proxy tra backend e client. Per ulteriori informazioni, consulta la sezione Target proxy.

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 delle applicazioni esterno globale invia una richiesta al backend, il carico aggiunge intestazioni delle richieste.

    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 dell'autorizzazione mancante dal pacchetto di controllo di integrità, potrebbe non riuscire.

  • Il bilanciatore del carico delle applicazioni esterno globale imposta le intestazioni di risposta prima di restituire il risposte al cliente.

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

Ogni intestazione deve essere specificata come una 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 di intestazione HTTP (secondo RFC 7230).
  • Il nome dell'intestazione non deve essere X-User-IP o CDN-Loop.
  • Non utilizzare le seguenti intestazioni hop-by-hop: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization e Proxy-Authenticate. In conformità con RFC 2616, non vengono archiviate nelle cache né propagate dai proxy di destinazione.
  • Il nome dell'intestazione non deve iniziare con X-Google, X-Goog-, X-GFE o X-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 RFC 7230, con 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. Un elenco di variabili consentito nel valore dell'intestazione è la sezione successiva.

Ad esempio, potresti specificare un'intestazione con due nomi di variabili, per il client la regione e la città del cliente. Lo strumento a riga di comando gcloud ha un flag per specificare intestazioni delle richieste, --custom-request-header. Assicurati di utilizzare solo le virgolette (') 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 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 di 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 per i casi d'uso CORS (condivisione delle risorse tra origini).
client_rtt_msec Tempo stimato di trasmissione andata e ritorno 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 fluido è 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 client. Questo è un codice regione Unicode CLDR, come 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 a all'indirizzo IP del client. Si tratta di un ID di suddivisione CLDR Unicode, come USCA o CAON. Questi codici Unicode vengono derivato 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 sono presenti elenco canonico di valori validi per questa variabile. I nomi delle città possono deve 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'IP del client che sia l'ultimo indirizzo nel X-Forwarded-For dell'intestazione, a meno che il client non utilizzi un proxy o L'intestazione X-Forwarded-For è 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 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. Questo corrisponde all'ultimo indirizzo IP della X-Forwarded-For intestazione.
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 (RFC) 6066), se fornito 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 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 è 4 esadecimali definite 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 JA3 Impronta TLS/SSL se il client si connette tramite HTTPS, HTTP/2 o HTTP/3.

Il bilanciatore del carico espande le variabili in stringhe vuote quando non può determinare sui propri valori. Ad esempio:

  • Variabili di posizione geografica quando l'indirizzo IP è sconosciuto
  • Parametri TLS quando TLS non è in uso
  • {origin_request_header} quando la richiesta non include un'intestazione Origin
  • L'intestazione {cdn_cache_status} quando è 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 al fine di migliorare l'accuratezza e riflettere l'area geografica cambiamenti 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 l'inserimento 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 parentesi graffa chiusa (}).

Intestazioni TLS personalizzate reciproche

Le seguenti variabili di intestazione aggiuntive sono disponibili se il protocollo TLS reciproco (mTLS) è configurato sul proxy 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 viene verificata la catena di certificati client in base a una TrustStore; altrimenti false.
client_cert_error Stringhe predefinite che rappresentano le condizioni di errore. Per ulteriori informazioni informazioni 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 è impostato su client_cert_serial_number_exceeded_size_limit e il numero di serie sia impostato su una stringa vuota.
client_cert_spiffe_id

La ID SPIFFE dal campo Subject Alternative Name (SAN). 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, il valore client_cert_error è impostato su client_cert_spiffe_id_exceeded_size_limit.
client_cert_uri_sans

Elenco con codifica Base64 separato da virgole 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, Il valore di client_cert_error è impostato su client_cert_uri_sans_exceeded_size_limit e l'elenco separato da virgole sia impostato su una stringa vuota.
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_dnsname_sans è più lungo di 512 byte, Il valore di client_cert_error è impostato su client_cert_dnsname_sans_exceeded_size_limit e l'elenco separato da virgole sia impostato su una stringa vuota.
client_cert_valid_not_before Timestamp (RFC 3339) data) prima del quale il certificato client non è valido. Ad esempio, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after Timestamp (RFC 3339) data di inizio) 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_issuer_dn è più lungo di 512 byte, viene aggiunta la stringa client_cert_issuer_dn_exceeded_size_limit a client_cert_error e client_cert_issuer_dn sia impostato su una stringa vuota.
client_cert_subject_dn

Codifica DER con codifica Base64 dell'intero campo Subject del certificato.

Se client_cert_subject_dn è più lungo di 512 byte, la stringa client_cert_subject_dn_exceeded_size_limit è aggiunto a client_cert_error e client_cert_subject_dn sia impostato su una stringa vuota.
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 con RFC 9440. Questo indica che il certificato binario DER è codificato utilizzando Base64 e delimitato da i due punti ai lati.

Se client_cert_leaf supera i 16 kB non codificati, la stringa client_cert_validated_leaf_exceeded_size_limit aggiunto a client_cert_error e client_cert_leaf impostati in una stringa vuota.
client_cert_chain

L'elenco di certificati delimitato da virgole, in ordine TLS standard, della catena di certificati client per una connessione mTLS stabilita il certificato client ha superato la convalida, esclusa la Fogliolina certificato. La codifica del certificato è conforme a RFC 9440.

Se la dimensione combinata di client_cert_leaf e client_cert_chain prima della codifica Base64 supera i 16 kB, il valore la stringa client_cert_validated_chain_exceeded_size_limit è aggiunto a client_cert_error e client_cert_chain sia impostato su una stringa vuota.

Configura 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, svuotamento della connessione). timeout, criteri di sicurezza).
  6. In Intestazioni delle richieste personalizzate, fai clic su Aggiungi intestazione.
  7. Inserisci il Nome intestazione e il Valore intestazione per la richiesta personalizzata. intestazione.
  8. Inserisci eventuali intestazioni aggiuntive della richiesta personalizzate.
  9. Fai clic su Salva.

Per rimuovere l'intestazione di una 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, svuotamento della connessione). timeout, criteri di sicurezza).
  6. Fai clic sulla X accanto al nome dell'intestazione della richiesta personalizzata che vuoi da rimuovere.
  7. Fai clic su Salva.

gcloud

Per specificare intestazioni delle richieste personalizzate, utilizza gcloud compute backend-services create o Comando 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 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

Invia una richiesta PATCH a 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.

Configura 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, svuotamento della connessione). timeout, criteri di sicurezza).
  6. In Intestazioni delle risposte personalizzate, fai clic su Aggiungi intestazione.
  7. Inserisci il Nome intestazione e il Valore intestazione per la risposta personalizzata. intestazione.
  8. Inserisci eventuali intestazioni di risposta personalizzate aggiuntive.
  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, svuotamento della connessione). timeout, criteri di sicurezza).
  6. Fai clic sulla X accanto al nome dell'intestazione della risposta personalizzata che vuoi da rimuovere.
  7. Fai clic su Salva.

gcloud

Per i servizi di backend, utilizza gcloud compute backend-services create o Comando 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 Method: backendServices.insert oppure Method: backendServices.update chiamata API.

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 viene sovrascritto il valore compilato dal bilanciatore del carico. In caso contrario vuoi che il criterio Google Cloud Armor venga sovrascritto, assicurati di non usano lo stesso nome.

Limitazioni

Le seguenti limitazioni si applicano alle intestazioni personalizzate utilizzate con il caricamento globale bilanciatori del carico:

  • 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 delle risposte 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 risposta.

Passaggi successivi