Creare intestazioni personalizzate nelle mappe URL

Questa pagina descrive il funzionamento delle intestazioni personalizzate nelle mappe di URL utilizzate dai bilanciatori del carico delle applicazioni esterni regionali, dai bilanciatori del carico delle applicazioni interni regionali e dai bilanciatori del carico delle applicazioni interni tra regioni.

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

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 invia 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 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 un la risposta desiderata al cliente.

Per attivare le intestazioni personalizzate per i bilanciatori del carico delle applicazioni esterni regionali, i bilanciatori del carico delle applicazioni interni regionali e i bilanciatori del carico delle applicazioni interni tra regioni, specifica un elenco di nomi e valori di intestazione nel file di configurazione della mappa di URL.

I nomi delle intestazioni devono avere le seguenti proprietà:

  • Il nome dell'intestazione deve essere una definizione valida del nome del campo dell'intestazione HTTP per RFC 7230.
  • Il nome dell'intestazione non deve essere X-User-IP.
  • Il nome dell'intestazione non deve iniziare con X-Google, X-Goog-, X-GFE o X-Amz-.
  • Il nome dell'intestazione non deve essere Host o authority. Sia Host che authority sono parole chiave speciali riservate da Google Cloud. Non puoi modificare queste righe di intestazione per i bilanciatori del carico basati su Envoy. Ti consigliamo invece di creare altre intestazioni personalizzate (ad esempio, MyHost) per non interferire con i nomi delle intestazioni riservate.
  • Un nome di intestazione non deve comparire più di una volta nell'elenco delle intestazioni.

I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. Quando i nomi delle intestazioni vengono passati a HTTP/2 , il protocollo HTTP/2 codifica i nomi delle intestazioni in lettere minuscole.

I valori delle intestazioni devono avere le seguenti proprietà:

  • 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 non può essere vuoto. Le intestazioni vuote vengono rifiutate.
  • Il valore dell'intestazione può includere una o più variabili, racchiuse tra parentesi graffe, che si espandono ai valori forniti dal bilanciatore del carico. Per un elenco completo consentite nel valore dell'intestazione, consulta Variabili che possono essere visualizzate nel valore dell'intestazione.

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

Aggiungere intestazioni di richiesta o risposta

Per aggiungere intestazioni di richiesta o risposta, utilizza gcloud CLI per modificare la mappa URL come segue:

regionale

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION
    

Di seguito è riportato un file YAML di esempio che mostra come utilizzare le variabili negli intestazioni personalizzate:

   defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
   name: regional-lb-map
   region: region/REGION
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: regions/REGION/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requesteHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

tra regioni

    gcloud compute url-maps edit URL_MAP_NAME \
        --global
    

Di seguito è riportato un file YAML di esempio che mostra come utilizzare le variabili in intestazioni:

   defaultService: global/backendServices/BACKEND_SERVICE_1
   name: global-lb-map
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: global/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: global/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requesteHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

Osserva i seguenti comportamenti:

  • Se un'intestazione di risposta con variabili personalizzate risolve in una stringa vuota, viene rimossa.
  • Se un'intestazione della richiesta con variabili personalizzate risolve in una stringa vuota, viene conservata con un segnaposto di stringa vuota.
  • Se l'intestazione di una richiesta personalizzata include una variabile personalizzata e un client in entrata include anche la stessa intestazione, il valore di intestazione della richiesta del client sostituito con il nuovo valore fornito dall'intestazione personalizzata del bilanciatore del carico.

Variabili che possono apparire nel valore dell'intestazione

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

Variabile Descrizione
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_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 appiattito è un algoritmo che gestisce le variazioni e le anomalie che possono verificarsi nelle misurazioni del RTT.
client_ip_address L'indirizzo IP del client. Di solito corrisponde all'indirizzo IP del client che è 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 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 tra HTTP/1.0, HTTP/1.1, HTTP/2 o HTTP/3.
origin_request_header Riflette il valore dell'intestazione Origin nella richiesta per i casi d'uso della condivisione delle risorse tra origini (CORS).
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 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 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 è 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 è 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
  • Il {origin_request_header} quando la richiesta non include un Origin intestazione

I valori geografici sono stime basate sull'indirizzo IP del cliente. Di tanto in tanto nel tempo, Google aggiorna i dati che forniscono questi valori per migliorare l'accuratezza e riflettere i cambiamenti geografici e politici. Anche se l'originale L'intestazione X-Forwarded-For contiene informazioni valide sulla posizione; stime di Google le località dei client utilizzando le informazioni sull'indirizzo IP di origine contenute nei pacchetti ricevute dal bilanciatore del carico.

Intestazioni personalizzate TLS reciproca

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 un TrustStore; altrimenti 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, la stringa client_cert_serial_number_exceeded_size_limit aggiunto a client_cert_error e il numero di serie sia impostato su una stringa vuota.
client_cert_spiffe_id

La ID SPIFFE nel 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, la stringa client_cert_spiffe_id_exceeded_size_limit viene aggiunta a client_cert_error.

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, la stringa client_cert_uri_sans_exceeded_size_limit è stata aggiunta client_cert_error 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, la stringa client_cert_dnsname_sans_exceeded_size_limit viene aggiunta a client_cert_error e l'elenco separato da virgole viene 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

Campo emittente completo con codifica Base64 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

Campo Oggetto completo del certificato con codifica Base64.

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: il certificato DER binario è codificato utilizzando Base64 (senza interruzioni di riga, spazi o altri caratteri esterni all'alfabeto Base64) e delimitato con 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 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.

Limitazioni

Il seguente limite si applica alle intestazioni personalizzate utilizzate con il caricamento a livello di regione bilanciatori del carico:

  • Non puoi configurare intestazioni personalizzate sui servizi di backend regionali utilizzati dai bilanciatori del carico delle applicazioni esterni regionali, dai bilanciatori del carico delle applicazioni interni regionali e dai servizi di backend globali utilizzati dai bilanciatori del carico delle applicazioni interni tra regioni.
  • Le seguenti variabili di intestazione personalizzate non sono supportate con Bilanciatori del carico delle applicazioni esterni regionali:
    • cdn_cache_id
    • cdn_cache_status
    • client_region_subdivision
    • client_city
    • client_city_lat_long