Cette page décrit le fonctionnement des en-têtes personnalisés dans les mappages d'URL utilisés par les équilibreurs de charge d'application externes régionaux, les équilibreurs de charge d'application internes régionaux et les équilibreurs de charge d'application internes interrégionaux.
Les en-têtes de requêtes et de réponses personnalisés vous permettent de spécifier des en-têtes supplémentaires que l'équilibreur de charge peut ajouter aux requêtes et aux réponses HTTP(S). En fonction des informations détectées par l'équilibreur de charge, ces en-têtes peuvent inclure les informations suivantes :
- Latence vis-à-vis du client
- Emplacement géographique de l'adresse IP du client
- Paramètres de la connexion TLS
Avant de commencer
Si nécessaire, installez la dernière version de Google Cloud CLI :
gcloud components update
Fonctionnement des en-têtes personnalisés
Les en-têtes personnalisés fonctionnent comme suit :
Lorsque l'équilibreur de charge envoie une requête au backend, il ajoute des en-têtes de requêtes.
L'équilibreur de charge définit les en-têtes de réponse avant de renvoyer une réponse au client.
Pour activer les en-têtes personnalisés pour les équilibreurs de charge d'application externes régionaux, les équilibreurs de charge d'application internes régionaux et les équilibreurs de charge d'application internes interrégionaux, vous devez spécifier une liste de noms d'en-têtes et de valeurs d'en-tête dans la configuration du mappage d'URL.
Les noms d'en-têtes doivent présenter les propriétés suivantes :
- Le nom d'en-tête doit être une définition de nom de champ d'en-tête HTTP valide conformément à la RFC 7230.
- Le nom d'en-tête ne peut pas être
X-User-IP. - Le nom d'en-tête ne doit pas commencer par
X-Google,X-Goog-,X-GFEouX-Amz-. - Le nom d'en-tête ne peut pas être
Hostniauthority.Hostetauthoritysont des mots clés spéciaux réservés par Google Cloud. Vous ne pouvez pas modifier ces en-têtes pour les équilibreurs de charge basés sur Envoy. Nous vous recommandons plutôt de créer d'autres en-têtes personnalisés (par exemple,MyHost) afin de ne pas interférer avec les noms d'en-tête réservés. - Un nom d'en-tête ne doit pas apparaître plus d'une fois dans la liste des en-têtes.
Les noms d'en-têtes sont non sensibles à la casse. Lorsque des noms d'en-têtes sont transmis à un backend HTTP/2, le protocole HTTP/2 les encode en minuscules.
Les valeurs d'en-tête présentent les caractéristiques suivantes :
- La valeur d'en-tête doit être une définition de champ d'en-tête HTTP valide. Conformément à la RFC 7230, les formats obsolètes n'étant pas acceptés.
- Vous devez indiquer une valeur pour l'en-tête. Les en-têtes vides sont refusés.
- La valeur de l'en-tête peut contenir une ou plusieurs variables, délimitées par des accolades. C'est à l'équilibreur de charge de fournir les valeurs nécessaires à l'expansion des variables. Pour obtenir la liste complète des variables autorisées dans la valeur d'en-tête, consultez la section Variables pouvant apparaître dans la valeur d'en-tête.
Dans les valeurs d'en-tête, les espaces de début et de fin n'ont aucune importance et ne sont pas transmis au backend. Pour permettre l'utilisation des accolades dans les valeurs d'en-tête, l'équilibreur de charge interprète deux accolades ouvrantes ({{) comme une seule ({), et deux accolades fermantes (}}) comme une seule (}).
Ajouter des en-têtes de requête ou de réponse
Pour ajouter des en-têtes de requête ou de réponse, utilisez gcloud CLI pour modifier le mappage d'URL comme suit :
régional
gcloud compute url-maps edit URL_MAP_NAME \
--region=REGION
Voici un exemple de fichier YAML qui montre comment utiliser des variables dans des en-têtes personnalisés :
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
interrégional
gcloud compute url-maps edit URL_MAP_NAME \
--global
Voici un exemple de fichier YAML qui montre comment utiliser des variables dans des en-têtes personnalisés :
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
Notez les comportements suivants :
- Si un en-tête de réponse avec des variables personnalisées renvoie une chaîne vide, il est supprimé.
- Si un en-tête de requête avec des variables personnalisées renvoie une chaîne vide, il est conservé avec un espace réservé de chaîne vide.
- Si un en-tête de requête personnalisé inclut une variable personnalisée et qu'une requête cliente entrante inclut également le même en-tête, la valeur de l'en-tête de requête cliente est remplacée par la nouvelle valeur fournie par l'en-tête personnalisé de l'équilibreur de charge.
Variables pouvant apparaître dans la valeur d'en-tête
Les variables suivantes peuvent apparaître dans les valeurs d'en-têtes personnalisés.
| Variable | Description |
|---|---|
client_region |
Pays (ou région) associé à l'adresse IP du client. Il s'agit d'un code de région CLDR au format Unicode, tel que US ou FR. Pour la plupart des pays, ces codes correspondent directement aux codes ISO-3166-2.
|
client_rtt_msec |
Temps de transmission aller-retour estimé entre l'équilibreur de charge et le client HTTP(S), en millisecondes. Il s'agit du paramètre de temps d'aller-retour lissé (SRTT, Smoothed Round-Trip Time) mesuré par la pile TCP de l'équilibreur de charge, conformément à la RFC 2988. Le DAR lissé est un algorithme qui traite les variations et les anomalies pouvant se produire dans les mesures de latence DAR. |
client_ip_address |
Adresse IP du client. Cette valeur est généralement identique à l'adresse IP du client qui figure comme avant-dernière adresse dans l'en-tête X-Forwarded-For, sauf si le client utilise un proxy ou si l'en-tête X-Forwarded-For a été altéré. |
client_port |
Port source du client. |
client_encrypted |
true si la connexion entre le client et l'équilibreur de charge est chiffrée (via HTTPS, HTTP/2 ou HTTP/3), sinon false.
|
client_protocol |
Protocole HTTP utilisé pour la communication entre le client et l'équilibreur de charge. Valeurs possibles : HTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3.
|
origin_request_header |
Correspond à la valeur de l'en-tête Origin dans la requête pour les cas d'utilisation CORS (Cross-Origin Resource Sharing). |
server_ip_address |
Adresse IP de l'équilibreur de charge auquel le client se connecte. Cela peut être utile lorsque plusieurs équilibreurs de charge partagent des backends communs. Cette valeur est identique à la dernière adresse IP de l'en-tête X-Forwarded-For.
|
server_port |
Numéro du port de destination auquel le client se connecte. |
tls_sni_hostname |
Indication du nom du serveur (telle que définie dans la RFC 6066), si ce nom est fourni par le client lors du handshake TLS ou QUIC. Le nom d'hôte est converti en minuscules et tous les points se trouvant à la fin du nom sont supprimés. |
tls_version |
Version de TLS négociée entre le client et l'équilibreur de charge lors du handshake SSL. Les valeurs possibles sont TLSv1,
TLSv1.1, TLSv1.2 et TLSv1.3. Si le client se connecte à l'aide de QUIC au lieu de TLS, la valeur est QUIC.
|
tls_cipher_suite |
Suite de chiffrement négociée lors du handshake TLS. La valeur se compose de quatre chiffres hexadécimaux. Elle est définie par le Registre de l'IANA portant sur la suite de chiffrement TLS. Par exemple, 009C correspond à TLS_RSA_WITH_AES_128_GCM_SHA256. Cette valeur est vide pour QUIC et pour les connexions clientes non chiffrées.
|
tls_ja3_fingerprint |
Empreinte TLS/SSL JA3 si le client se connecte via HTTPS, HTTP/2 ou HTTP/3. |
L'équilibreur de charge procède à l'expansion des variables sous forme de chaînes vides lorsqu'il ne peut pas déterminer leur valeur. Exemple :
- Variables représentant des emplacements géographiques lorsque l'emplacement de l'adresse IP est inconnu
- Paramètres TLS lorsque TLS n'est pas utilisé
- Valeur
{origin_request_header}lorsque la requête n'inclut pas d'en-têteOrigin.
Les valeurs géographiques sont des estimations basées sur l'adresse IP du client. De temps à autre, Google actualise les données qui fournissent ces valeurs afin d'améliorer la précision et de refléter les changements géographiques et politiques. Même si l'en-tête X-Forwarded-For d'origine contient des informations de localisation valides, Google estime les emplacements clients en utilisant les informations d'adresse IP source contenues dans les paquets reçus par l'équilibreur de charge.
En-têtes TLS mutuels personnalisés
Les variables d'en-tête supplémentaires suivantes sont disponibles si le protocole TLS mutuel (mTLS) est configuré sur le TargetHttpsProxy de l'équilibreur de charge.
| Variable | Description |
|---|---|
client_cert_present |
true si le client a fourni un certificat lors du handshake TLS. Sinon, false.
|
client_cert_chain_verified |
true si la chaîne de certificats client est validée par rapport à une configuration TrustStore configurée ou false.
|
client_cert_error |
Chaînes prédéfinies représentant les conditions d'erreur. Pour plus d'informations sur les chaînes d'erreur, consultez la section Modes de validation des clients mTLS. |
client_cert_sha256_fingerprint |
Empreinte SHA-256 du certificat client, encodée en base64. |
client_cert_serial_number |
Numéro de série du certificat client.
Si le numéro de série est plus de 50 octets, la chaîne client_cert_serial_number_exceeded_size_limit est ajoutée à client_cert_error et le numéro de série est défini sur une chaîne vide. |
client_cert_spiffe_id |
L'ID SPIFFE du champ "Autre nom de l'objet (SAN)". Si la valeur n'est pas valide ou dépasse 2 048 octets, l'ID SPIFFE est défini sur une chaîne vide. Si l'ID SPIFFE dépasse 2 048 octets, la chaîne |
client_cert_uri_sans |
Liste des extensions SAN de type URI encodées en base64, séparées par une virgule.
Les extensions SAN sont extraites du certificat client.
L'ID SPIFFE n'est pas inclus dans le champ Si |
client_cert_dnsname_sans |
Liste des extensions SAN de type DNSName encodées en base64, séparées par une virgule. Les extensions SAN sont extraites du certificat client. Si |
client_cert_valid_not_before |
Horodatage (format de chaîne de date RFC 3339) avant lequel le certificat client n'est pas valide.
Par exemple, 2022-07-01T18:05:09+00:00.
|
client_cert_valid_not_after |
Horodatage (format de chaîne de date RFC 3339) après lequel le certificat client n'est pas valide.
Par exemple, 2022-07-01T18:05:09+00:00.
|
client_cert_issuer_dn |
Champ Issuer (émetteur) complet, encodé en base64, tiré du certificat. Si |
client_cert_subject_dn |
Champ Subject (objet) complet, encodé en base64, tiré du certificat. Si |
client_cert_leaf |
Certificat d'entité finale du client pour une connexion mTLS établie où le certificat a été validé. L'encodage des certificats est conforme à RFC 9440 : le certificat DER binaire est encodé en base64 (sans sauts de ligne, espaces ni autres caractères en dehors de l'alphabet en base64) et est délimité par des signes deux-points de chaque côté. Si |
client_cert_chain |
Liste de certificats séparés par une virgule (dans l'ordre TLS standard) de la chaîne de certificats client pour une connexion mTLS établie où le certificat client a été validé, sans inclure le certificat d'entité finale. L'encodage du certificat est conforme à la norme RFC 9440. Si la taille combinée de |
Limites
La limite suivante s'applique aux en-têtes personnalisés utilisés avec les équilibreurs de charge régionaux :
- Vous ne pouvez pas configurer d'en-têtes personnalisés sur les services de backend régionaux utilisés par les équilibreurs de charge d'application externes régionaux, les équilibreurs de charge d'application internes régionaux et les services de backend globaux utilisés par les équilibreurs de charge d'application internes interrégionaux.
- Les variables d'en-tête personnalisées suivantes ne sont pas compatibles avec les équilibreurs de charge d'application externes régionaux :
cdn_cache_idcdn_cache_statusclient_region_subdivisionclient_cityclient_city_lat_long