Créer des en-têtes de requête définis par l'utilisateur

Les en-têtes de requêtes définis par l'utilisateur permettent de spécifier des en-têtes supplémentaires qui sont ajoutés aux requêtes par l'équilibreur de charge. Ces en-têtes peuvent contenir des informations sur la connexion client qui sont connues par l'équilibreur de charge, parmi lesquelles la latence vis-à-vis du client, l'emplacement géographique de son adresse IP, ou encore les paramètres de la connexion TLS.

Les en-têtes de requêtes définis par l'utilisateur sont acceptés pour les services de backend associés aux équilibreurs de charge HTTP(S).

Notez que les équilibreurs de charge HTTP(S) ajoutent par défaut certains en-têtes à toutes les requêtes HTTP(S) qu'ils relaient aux backends. Pour plus d'informations à ce sujet, reportez-vous à la section Proxys cibles.

Fonctionnement des en-têtes de requêtes définis par l'utilisateur

Pour activer les en-têtes de requêtes définis par l'utilisateur, vous devez spécifier une liste d'en-têtes dans une propriété de la ressource du service de backend. L'équilibreur de charge ajoute les en-têtes aux requêtes qu'il transfère aux backends.

Spécifiez chaque en-tête en tant que chaîne header-name:header-value. Le nom (header-name) et la valeur (header-value) de l'en-tête doivent être séparés par deux points. Les noms d'en-tête présentent les caractéristiques 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 ni CDN-Loop.
  • Le nom d'en-tête ne doit pas commencer par X-Google, X-Goog-, X-GFE ou X-Amz-.
  • Un nom d'en-tête ne doit pas apparaître plus d'une fois dans la liste des en-têtes ajoutés.

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).
  • La valeur de l'en-tête peut être vide.
  • 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. Vous trouverez une liste des variables autorisées pour la valeur d'en-tête dans la section qui suit.

Par exemple, vous pouvez spécifier un en-tête avec deux noms de variables, l'un représentant la région du client et l'autre représentant sa ville cliente. L'outil de ligne de commande gcloud possède une option permettant de spécifier des en-têtes de requêtes : --custom-request-header. Exemple :

    --custom-request-header 'X-Client-Geo-Location:{client_region},{client_city}'

Pour les clients situés à Mountain View, en Californie, l'équilibreur de charge ajoute l'en-tête ci-dessous :

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

Le format général de cet indicateur est le suivant :

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Les valeurs d'en-tête doivent être placées entre accolades. Exemple :

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

N'utilisez que des guillemets droits (') dans cette commande.

Pour en savoir plus sur la configuration des en-têtes de requêtes personnalisés, consultez la section Utiliser des en-têtes de requêtes définis par l'utilisateur.

Variables pouvant apparaître dans la valeur d'en-tête

Les variables suivantes peuvent apparaître dans les valeurs d'en-têtes de requêtes.

Variable Description
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.
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_region_subdivision Subdivision (une province ou un État, par exemple) du pays associée à l'adresse IP du client. Il s'agit d'un ID de subdivision CLDR au format Unicode, tel que "USCA" ou "CAON". Ces codes Unicode sont dérivés des subdivisions définies par la norme ISO-3166-2.
client_city Nom de la ville d'origine de la requête, par exemple "Mountain View" pour Mountain View, Californie. Il n'existe pas de liste canonique de valeurs valides pour cette variable. Les noms des villes peuvent contenir des lettres, des chiffres et des espaces au format US-ASCII, ainsi que les caractères suivants : ``!#$%&'*+-.^_`|~``.
client_city_lat_long Latitude et longitude de la ville d'origine de la requête. Par exemple, "37.386051,-122.083851" pour une requête provenant de Mountain View.
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 s'est connecté à l'aide de QUIC au lieu de TLS, la valeur sera "QUIC".
tls_cipher_suite Suite de chiffrement négociée lors du handshake TLS. La valeur se compose de quatre caractères 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.

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, par exemple pour les variables représentant des emplacements géographiques lorsque l'emplacement de l'adresse IP est inconnu, ou encore pour les paramètres TLS lorsque TLS n'est pas utilisé.

Les valeurs géographiques (régions, subdivisions et villes) 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.

Les en-têtes ajoutés par l'équilibreur de charge écrasent les en-têtes existants portant le même nom. Les noms d'en-têtes ne sont pas sensibles à la casse. Lorsque des noms d'en-têtes sont transmis à un backend HTTP/2, le protocole HTTP/2 les encode en minuscules.

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 (}).

Utiliser des en-têtes de requêtes définis par l'utilisateur

Les restrictions suivantes s'appliquent aux en-têtes de requêtes définis par l'utilisateur :

  • Vous pouvez spécifier un maximum de 16 en-têtes de requêtes personnalisés par service de backend.
  • La taille totale de l'ensemble des en-têtes de requêtes définis par l'utilisateur pour un service de backend donné (nom et valeur combinés, avant expansion des variables) ne doit pas dépasser 8 Ko.

Console

Pour ajouter des en-têtes de requêtes personnalisés à un service de backend existant, procédez comme suit :

  1. Accédez à la page de résumé de l'équilibrage de charge.
    Accéder à la page Équilibrage de charge
  2. Cliquez sur Backends.
  3. Cliquez sur le nom d'un service de backend.
  4. Cliquez sur Modifier .
  5. Cliquez sur Configurations avancées (affinité de session, délai avant expiration du drainage de connexion, règles de sécurité).
  6. Sous En-têtes de requêtes personnalisés, cliquez sur Ajouter un en-tête.
  7. Renseignez les champs Nom de l'en-tête et Valeur d'en-tête pour l'en-tête de requête personnalisé.
  8. Créez d'autres en-têtes de requêtes personnalisés.
  9. Cliquez sur Enregistrer.

Pour supprimer un en-tête de requête personnalisé d'un service de backend, procédez comme suit :

  1. Accédez à la page de résumé de l'équilibrage de charge.
    Accéder à la page Équilibrage de charge
  2. Cliquez sur Backends.
  3. Cliquez sur le nom d'un service de backend.
  4. Cliquez sur Modifier .
  5. Cliquez sur Configurations avancées (affinité de session, délai avant expiration du drainage de connexion, règles de sécurité).
  6. Cliquez sur le X situé à côté du nom de l'en-tête de requête personnalisé que vous souhaitez supprimer.
  7. Cliquez sur Enregistrer.

gcloud

Pour créer un service de backend avec des en-têtes de requêtes définis par l'utilisateur :

gcloud compute backend-services create NAME \
  --global-health-checks \
  --global \
  --protocol HTTPS \
  --https-health-check https-basic-check \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

Pour ajouter d'autres en-têtes de requêtes, spécifiez pour chacun un nom et une valeur d'en-tête uniques en répétant l'option --custom-request-header.

Pour ajouter des en-têtes de requêtes définis par l'utilisateur à un service de backend existant, procédez comme suit :

gcloud compute backend-services update NAME \
  --global \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

Notez que les en-têtes de requêtes spécifiés dans la commande présentée ci-dessus remplacent l'intégralité des en-têtes figurant déjà dans le service de backend.

Pour supprimer tous les en-têtes d'un service de backend, procédez comme suit :

gcloud compute backend-services update NAME \
  --global \
  --no-custom-request-headers

API

Envoyez une requête PATCH à la méthode backendServices.patch.

PATCH https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/backendServices/[BACKEND_SERVICE_NAME]
"customRequestHeaders": [
  "client_city:Mountain View"
]

Étape suivante