Attributs acceptés

Lorsque vous configurez des extensions à l'aide de plug-ins ou de callouts, vous pouvez spécifier les attributs de requête et de connexion à transférer aux services d'extension. Cette page décrit les attributs compatibles et identifie ceux qui sont disponibles pour chaque type d'extension.

En configurant des extensions pour transférer des attributs spécifiques, vous pouvez :

  • Prendre des décisions de routage dynamiques
  • Enrichissez les en-têtes de requête avec des informations sur le client.
  • Mettez en œuvre des règles de sécurité personnalisées basées sur l'emplacement du client ou les paramètres TLS.
  • Générez des journaux personnalisés détaillés.

Vous pouvez spécifier des attributs avec le champ forwardAttributes dans la configuration YAML pour les extensions de plug-in et de callout. Par exemple, pour les extensions de trafic, consultez Configurer une extension de trafic.

Spécifiez les attributs avec forwardAttributes pour les types d'extensions suivants :

  • Extensions périphériques Cloud Load Balancing (LbEdgeExtension) sur les équilibreurs de charge d'application externes globaux
  • Route Cloud Load Balancing et extensions de trafic (LbRouteExtension, LbTrafficExtension) sur les équilibreurs de charge d'application
  • Extensions d'autorisation (AuthzExtension) utilisant ext_proc sur les équilibreurs de charge d'application
  • Extensions en périphérie Media CDN (CdnEdgeExtension) sur les services Media CDN Edge Cache

Attributs de requête

Vous pouvez extraire et transférer les attributs suivants à partir des requêtes :

Attribut Type LbEdge LbRoute LbTraffic Authz CdnEdge Description et différences de comportement
request.method string ✓ ✓ ✓ ✓ ✓ Méthode de requête HTTP, telle que GET ou POST.
request.host string ✓ ✓ ✓ ✓ ✓ Équivalent pratique à request.headers['host'].
request.path string ✓ ✓ ✓ ✓ ✓ Chemin d'URL HTTP demandé.
request.query string ✓ ✓ ✓ ✓ ✓ Requête d'URL HTTP au format name1=value&name2=value2.
request.scheme string ✓ ✓ ✓ ✓ ✓ Schéma d'URL HTTP (http ou https). Les valeurs sont en minuscules.
request.origin string — — ✓ ✓ — Valeur de l'en-tête de requête Origin pour les cas d'utilisation de partage de ressources interorigines (CORS).
request.user_agent_family string ✓ — ✓ — — Chaîne de la famille de user-agents analysée. Compatible uniquement avec les équilibreurs de charge d'application externes globaux.
request.device_request_type string ✓ — ✓ — — Catégorie de classification de l'appareil. Compatible uniquement avec les équilibreurs de charge d'application externes globaux.
request.backend_service_name string — — ✓ ✓ — Service de backend cible. Non applicable aux extensions de périphérie (LbEdgeExtension ou CdnEdgeExtension).
request.backend_service_project_number int — — ✓ ✓ — Numéro du projet du service de backend dans le VPC partagé. Non applicable aux extensions de périphérie.
request.mcp_method string — — — ✓ — Nom de la méthode MCP (Model Context Protocol).

Attributs de connexion

Vous pouvez extraire et transférer les attributs suivants à partir des connexions :

Attribut Type LbEdge LbRoute LbTraffic Authz CdnEdge Description et différences de comportement
source.ip string ✓ ✓ ✓ ✓ — Adresse IP client.
source.port int ✓ ✓ ✓ ✓ ✓ Numéro de port source du client.
source.client_region string ✓ — ✓ — ✓ Code de région ISO-3166-1 ou CLDR à deux lettres associé à l'adresse IP client (par exemple, US ou DE).
source.client_region_subdivision string ✓ — ✓ — — Code de subdivision de la région, par exemple pour un État ou une province. Compatible uniquement avec les équilibreurs de charge d'application externes globaux.
source.client_city string ✓ — ✓ — — Ville associée à l'adresse IP client. Compatible uniquement avec les équilibreurs de charge d'application externes globaux.
source.client_city_lat_long string ✓ — ✓ — — Latitude et longitude associées à la ville du client. Compatible uniquement avec les équilibreurs de charge d'application externes globaux.
destination.ip string — — ✓ ✓ — Adresse IP de l'équilibreur de charge auquel le client se connecte.
destination.port int — — ✓ ✓ — Numéro du port de destination auquel le client se connecte.
connection.client_encrypted Bool — — ✓ ✓ — La valeur est true si la connexion entre le client et l'équilibreur de charge est chiffrée (via HTTPS, HTTP/2 ou HTTP/3), sinon false.
connection.protocol string — — ✓ ✓ — Protocole HTTP utilisé pour la communication (HTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3).
connection.sni string ✓ — ✓ ✓ ✓ Indication du nom du serveur (SNI) demandée de la connexion TLS en aval.
connection.tls_version string ✓ — ✓ ✓ ✓ Version TLS négociée avec le client (TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 ou QUIC).
connection.tls_cipher_suite string — — ✓ ✓ — Suite de chiffrement hexadécimale à quatre chiffres négociée lors du handshake TLS (par exemple, 009C).
connection.tls_ja3_fingerprint string — — ✓ — — Empreinte TLS/SSL JA3 si le client se connecte via HTTPS, HTTP/2 ou HTTP/3.
connection.tls_ja4_fingerprint string ✓ — ✓ — — Empreinte TLS/SSL JA4 si le client se connecte via HTTPS, HTTP/2 ou HTTP/3.
connection.client_rtt_msec int — — ✓ ✓ — Délai aller-retour (DAR) du client, mesuré en millisecondes.
connection.sha256_peer_certificate_digest string ✓ — ✓ ✓ — Hachage du certificat de pair SHA-256 encodé en hexadécimal.
connection.client_cert_present Bool — — ✓ ✓ — La valeur est true si le client a fourni un certificat lors du handshake TLS. Sinon, elle est définie sur false.
connection.client_cert_chain_verified Bool — — ✓ ✓ — La valeur est true si la chaîne de certificats client est validée par rapport à un TrustStore configuré. Sinon, elle est false.
connection.client_cert_error string — — ✓ ✓ — Chaînes prédéfinies représentant les conditions d'erreur mTLS. Pour en savoir plus, consultez Modes de validation des clients mTLS.
connection.client_cert_serial_number string — — ✓ ✓ — Numéro de série du certificat client.
connection.client_cert_spiffe_id string — — ✓ ✓ — L'ID SPIFFE du champ "Autre nom de l'objet (SAN)".
connection.client_cert_uri_sans string — — ✓ ✓ — Liste d'extensions SAN d'URI encodées en base64, séparées par une virgule, extraites du certificat client.
connection.client_cert_dnsname_sans string — — ✓ ✓ — Liste d'extensions SAN DNSName encodées en base64 et séparées par une virgule, extraites du certificat client.
connection.client_cert_valid_not_before string — — ✓ ✓ — Horodatage (format RFC 3339) avant lequel le certificat client n'est pas valide.
connection.client_cert_valid_not_after string — — ✓ ✓ — Horodatage (format RFC 3339) après lequel le certificat client n'est pas valide.
connection.client_cert_issuer_dn string — — ✓ ✓ — Encodage DER encodé en base64 du champ Issuer du certificat.
connection.client_cert_subject_dn string — — ✓ ✓ — Encodage DER encodé en base64 du champ Subject du certificat.
connection.client_cert_leaf string — — ✓ ✓ — Certificat d'entité finale du client encodé en base64 pour une connexion mTLS établie et validée (RFC 9440).
connection.client_cert_chain string — — ✓ ✓ — Chaîne de certificats client encodée en base64 et séparée par une virgule, dans l'ordre TLS standard, à l'exclusion du certificat d'entité finale (RFC 9440).

Limites

  • Disponibilité des attributs : tous les attributs ne sont pas compatibles avec tous les types d'extensions. Pour en savoir plus, consultez le tableau sur cette page.

  • Configuration requise : pour envoyer des attributs à l'extension, vous devez les lister explicitement dans le champ forwardAttributes de la configuration de votre extension. Si vous ne listez pas un attribut dans ce champ, l'équilibreur de charge ou Media CDN ne transmet pas cet attribut spécifique à votre extension.

  • Limites de taille : vous pouvez configurer jusqu'à 16 attributs pour une seule extension.

  • Attributs mTLS : les attributs de certificat client (connection.client_cert_*) ne sont renseignés dans les données transmises à votre extension que si vous avez activé mTLS et que le client présente un certificat.