Créer des en-têtes personnalisés

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 HTTP(S) externe ajoute aux requêtes et aux réponses. Ces en-têtes peuvent contenir des informations sur la connexion client qui sont détectées 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 personnalisés sont acceptés pour les services de backend, tandis que les en-têtes de réponses personnalisés sont acceptés pour les services de backend et les buckets de backend.

L'équilibrage de charge HTTP(S) ajoute par défaut certains en-têtes à toutes les requêtes et réponses HTTP(S) qu'il relaie entre les backends et les clients. Pour en savoir plus, consultez la section Proxys cibles.

Avant de commencer

  • Si nécessaire, installez la dernière version du SDK Cloud :

    gcloud components update
    

Fonctionnement des en-têtes personnalisés

Les en-têtes personnalisés fonctionnent comme suit :

  • Lorsque l'équilibreur de charge HTTP(S) externe envoie une requête au backend, il ajoute des en-têtes de requêtes.

  • L'équilibreur de charge HTTP(S) externe définit des en-têtes de réponses avant de renvoyer les réponses au client.

Les en-têtes de requêtes et de réponses n'ont aucune incidence sur le comportement de la mise en cache ou de l'équilibreur de charge.

Pour activer les en-têtes personnalisés, vous devez spécifier une liste d'en-têtes dans une propriété du service de backend ou du bucket de backend.

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.

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
cdn_cache_id Code d'emplacement et ID de l'instance de cache utilisée pour diffuser la requête. Il s'agit de la même valeur que celle indiquée dans le champ jsonPayload.cacheId des journaux de requêtes Cloud CDN dans Logging.
cdn_cache_status État actuel du cache. Les valeurs peuvent être hit, miss, revalidated, stale, uncacheable ou disabled pour tout objet diffusé par un backend sur lequel Cloud CDN est activé.
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).
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 en Californie. Il n'existe pas de liste canonique de valeurs valides pour cette variable. Les noms de 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 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.

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ête Origin.
  • En-tête {cdn_cache_status} lorsqu'il est inclus dans un en-tête de requête

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 personnalisés

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 personnalisés, exécutez la commande suivante :

gcloud beta 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]'

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 personnalisés à un service de backend existant, exécutez la commande suivante :

gcloud beta compute backend-services update BACKEND_SERVICE_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 beta compute backend-services update BACKEND_SERVICE_NAME \
  --global \
  --no-custom-request-headers

API

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

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

Utiliser des en-têtes de réponses personnalisés

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 réponse 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 réponse personnalisé.
  8. Créez d'autres en-têtes de réponse 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 signe X situé à côté du nom de l'en-tête de réponse personnalisé que vous souhaitez supprimer.
  7. Cliquez sur Enregistrer.

gcloud

Pour les services de backend, exécutez la commande gcloud compute backend-services create ou gcloud compute backend-services update avec l'option --custom-response-header.

Pour les buckets de backend, exécutez la commande gcloud compute backend-buckets create ou gcloud compute backend-buckets update avec l'option --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]'

Exemple :

gcloud compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

API

Pour les buckets de backend, utilisez l'appel d'API Method: backendBuckets.insert ou Method: backendBuckets.update.

Pour les services de backend, utilisez l'appel d'API Method: backendServices.insert ou Method: backendServices.update.

Utilisez l'un des appels d'API suivants :

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

Ajoutez l'extrait suivant au corps de la requête JSON :

"cdnPolicy": {
  "customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
}

Définir des en-têtes de réponses pour Cloud Storage

Si vous devez configurer des en-têtes HTTP dans les réponses issues de Cloud Storage, telles que la règle CORS X-Frame-Options ou les en-têtes X-XSS-Protection, Google Cloud offre la possibilité d'utiliser des en-têtes personnalisés pour Cloud CDN avec Cloud Storage. Pour ce faire, configurez les en-têtes personnalisés au niveau du bucket backend de l'équilibreur de charge, comme décrit sur cette page.

Limites

Les limites suivantes s'appliquent aux en-têtes personnalisés :

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

Étape suivante