En esta página, se describe cómo funcionan los encabezados personalizados en los mapas de URL que usan los balanceadores de cargas de aplicaciones externos regionales, los balanceadores de cargas de aplicaciones internos regionales y los balanceadores de cargas de aplicaciones internos entre regiones.
Los encabezados de solicitud y respuesta personalizados te permiten especificar encabezados adicionales que el balanceador de cargas puede agregar a las solicitudes y respuestas HTTP(S). Según la información que detecte el balanceador de cargas, estos encabezados pueden incluir la siguiente información:
- Latencia para el cliente
- Ubicación geográfica de la dirección IP del cliente
- Parámetros de la conexión TLS
Antes de comenzar
Si es necesario, actualiza a la última versión de Google Cloud CLI:
gcloud components update
Cómo funcionan los encabezados personalizados
Los encabezados personalizados funcionan de la siguiente manera:
Cuando el balanceador de cargas realiza una solicitud al backend, el balanceador de cargas agrega encabezados de solicitud.
El balanceador de cargas establece los encabezados de respuesta antes de mostrar una respuesta al cliente.
A fin de habilitar los encabezados personalizados para los balanceadores de cargas de aplicaciones externos regionales, los balanceadores de cargas de aplicaciones internos regionales y los balanceadores de cargas de aplicaciones internos entre regiones, especifica una lista de nombres de encabezado y valores de encabezado en el archivo de configuración del mapa de URL.
Los nombres de encabezados deben tener las siguientes propiedades:
- El nombre del encabezado debe ser una definición de nombre de campo de encabezado HTTP válida (según RFC 7230).
- El nombre del encabezado no debe ser
X-User-IP. - El nombre del encabezado no debe comenzar con
X-Google,X-Goog-,X-GFEniX-Amz-. - El nombre del encabezado no debe ser
Hostniauthority.Hostyauthorityson palabras clave especiales que Google Cloud reserva. No puedes modificar estos encabezados para los balanceadores de cargas basados en Envoy. En cambio, te recomendamos que crees otros encabezados personalizados (por ejemplo,MyHost) para que no interfieras en los nombres de los encabezados reservados. - Un nombre de encabezado no debe aparecer más de una vez en la lista de encabezados.
Los nombres de encabezado no distinguen mayúsculas de minúsculas. Cuando los nombres de encabezado se pasan a un backend HTTP/2, el protocolo HTTP/2 codifica los nombres de encabezado como minúsculas.
Los valores de encabezado tienen las propiedades siguientes:
- El valor del encabezado debe ser una definición de campo de encabezado HTTP válida según RFC 7230, con formularios obsoletos no permitidos.
- El valor del encabezado no puede quedar en blanco. Se rechazan los encabezados en blanco.
- El valor del encabezado puede incluir una o más variables, entre llaves, que se expanden a los valores que proporciona el balanceador de cargas. Para obtener una lista completa de las variables permitidas en el valor del encabezado, consulta Variables que pueden aparecer en el valor del encabezado.
En los valores de encabezado, los espacios en blanco iniciales y finales son insignificantes y no se pasan al backend. Para permitir que se usen llaves en valores de encabezado, el balanceador de cargas interpreta dos llaves de apertura ({{) como una sola llave de apertura ({) y dos llaves de cierre (}}) como una sola llave de cierre (}).
Agrega encabezados de solicitud o respuesta
Para agregar encabezados de solicitud o respuesta, usa la CLI de gcloud a fin de editar el mapa de URL de la siguiente manera:
regional
gcloud compute url-maps edit URL_MAP_NAME \
--region=REGION
A continuación, se muestra un archivo YAML de muestra que indica cómo usar variables en encabezados personalizados:
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
entre regiones
gcloud compute url-maps edit URL_MAP_NAME \
--global
A continuación, se muestra un archivo YAML de muestra que indica cómo usar variables en encabezados personalizados:
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
Ten en cuenta los siguientes comportamientos:
- Si el encabezado de respuesta con variables personalizadas se resuelve en una cadena vacía, se quita.
- Si el encabezado de una solicitud con variables personalizadas se resuelve en una cadena vacía, se mantiene con un marcador de posición de cadena vacía.
- Si un encabezado de solicitud personalizado incluye una variable personalizada, y una solicitud de cliente entrante también incluye el mismo encabezado, el valor del encabezado de solicitud del cliente se reemplazará por el valor nuevo que proporcionó el encabezado del balanceador de cargas.
Variables que pueden aparecer en el valor del encabezado
Las siguientes variables pueden aparecer en los valores de encabezado personalizados.
| Variable | Descripción |
|---|---|
client_region |
El país (o región) asociado a la dirección IP del cliente. Este es un código regional CLDR de Unicode, como US o FR. (Para la mayoría de los países, estos códigos corresponden directamente a los códigos ISO-3166-2).
|
client_rtt_msec |
Tiempo estimado de transmisión de ida y vuelta entre el balanceador de cargas y el cliente HTTP(S), en milisegundos. Este es el parámetro de tiempo de ida y vuelta suavizado (SRTT) medido por la pila TCP del balanceador de cargas, según RFC 2988. El RTT suavizado es un algoritmo que se ocupa de las variaciones y las anomalías que pueden ocurrir en las mediciones de RTT. |
client_ip_address |
La dirección IP del cliente. Por lo general, es la misma que la dirección IP de cliente que es la próxima y última en el encabezado X-Forwarded-For, a menos que el cliente use un proxy o que el encabezado X-Forwarded-For se haya alterado. |
client_port |
El puerto de origen del cliente. |
client_encrypted |
true si la conexión entre el cliente y el balanceador de cargas está encriptada (con HTTPS, HTTP/2 o HTTP/3); de lo contrario, es false.
|
client_protocol |
El protocolo HTTP que se usa para la comunicación entre el cliente y el balanceador de cargas. Uno de HTTP/1.0, HTTP/1.1,
HTTP/2 o HTTP/3.
|
origin_request_header |
Refleja el valor del encabezado Origin en la solicitud de casos de uso de uso compartido de recursos entre dominios (CORS).
|
server_ip_address |
La dirección IP del balanceador de cargas al que se conecta el cliente. Esto puede ser útil cuando varios balanceadores de cargas comparten backends comunes. Es igual a la última dirección IP en el encabezado X-Forwarded-For.
|
server_port |
El número de puerto de destino al que se conecta el cliente. |
tls_sni_hostname |
Indicación del nombre del servidor (como se define en RFC 6066), si el cliente la proporciona durante el protocolo de enlace de TLS o QUIC. El nombre de host se pasa a minúsculas y se quita cualquier punto final. |
tls_version |
Versión de TLS negociada entre el cliente y el balanceador de cargas durante el protocolo de enlace SSL. Los valores posibles son TLSv1, TLSv1.1, TLSv1.2 y TLSv1.3. Si el cliente se conecta con QUIC en lugar de TLS, el valor es QUIC.
|
tls_cipher_suite |
Conjunto de cifrado negociado durante el protocolo de enlace TLS. El valor son cuatro dígitos hexadecimales definidos por IANA TLS Cipher Suite Registry, por ejemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor está vacío para QUIC y las conexiones de cliente no encriptadas.
|
tls_ja3_fingerprint |
Huella digital de TLS/SSL de JA3 si el cliente se conecta con HTTPS, HTTP/2 o HTTP/3. |
El balanceador de cargas expande las variables a strings vacías cuando no puede determinar sus valores. Por ejemplo:
- Las variables de ubicación geográfica cuando se desconoce la ubicación de la dirección IP
- Los parámetros de TLS cuando TLS no está en uso
{origin_request_header}cuando la solicitud no incluye un encabezadoOrigin
Los valores geográficos son estimaciones basadas en la dirección IP del cliente. De vez en cuando, Google actualiza los datos que proporcionan estos valores para mejorar la precisión y reflejar los cambios geográficos y políticos. Incluso si el encabezado X-Forwarded-For original contiene información de ubicación válida, Google estima las ubicaciones de los clientes mediante la información de la dirección IP de origen contenida en los paquetes que recibe el balanceador de cargas.
Encabezados personalizados de TLS mutuas
Las siguientes variables de encabezado adicionales están disponibles si se configura TLS mutua (mTLS) en el TargetHttpsProxy del balanceador de cargas.
| Variable | Descripción |
|---|---|
client_cert_present |
true si el cliente proporcionó un certificado durante el protocolo de enlace TLS, de lo contrario, es false.
|
client_cert_chain_verified |
true si la cadena de certificados de cliente se verifica con un TrustStore configurado, de lo contrario, es false.
|
client_cert_error |
Strings predefinidas que representan las condiciones de error. Para obtener más información sobre las strings de error, consulta los modos de validación de cliente mTLS. |
client_cert_sha256_fingerprint |
Huella digital SHA-256 codificada en base64 del certificado de cliente. |
client_cert_serial_number |
El número de serie del certificado de cliente.
Si el número de serie supera los 50 bytes, se agrega la cadena client_cert_serial_number_exceeded_size_limit en client_cert_error, y el número de serie se establece en una string vacía. |
client_cert_spiffe_id |
El ID de SPIFFE del campo Nombre alternativo del sujeto (SAN). Si el valor no es válido o supera los 2,048 bytes, el ID de SPIFFE se establece en una string vacía. Si el ID de SPIFFE supera los 2,048 bytes, la cadena |
client_cert_uri_sans |
Lista codificada en Base64 de comas de las extensiones de SAN de URI de tipo.
Las extensiones SAN se extraen del certificado de cliente.
El ID de SPIFFE no está incluido en el campo Si |
client_cert_dnsname_sans |
Lista codificada en Base64 de comas de las extensiones de SAN de tipo DNSName. Las extensiones de SAN se extraen del certificado de cliente. Si |
client_cert_valid_not_before |
Marca de tiempo (string con formato de fecha RFC 3339) antes de la cual el certificado de cliente no es válido.
Por ejemplo, 2022-07-01T18:05:09+00:00
|
client_cert_valid_not_after |
Marca de tiempo (formato de string de fecha RFC 3339) después de la cual el certificado de cliente no es válido.
Por ejemplo, 2022-07-01T18:05:09+00:00
|
client_cert_issuer_dn |
Campo completo de la entidad emisora codificado en Base64 del certificado. Si |
client_cert_subject_dn |
Campo completo del asunto codificado en base64 del certificado. Si |
client_cert_leaf |
El certificado de hoja del cliente para una conexión mTLS establecida en la que el certificado pasó la validación. La codificación del certificado cumple con el RFC 9440: el certificado binario DER está codificado con Base64 (sin saltos de línea, espacios ni otros caracteres fuera del alfabeto Base64) y delimitado por dos puntos en ambos lados. Si |
client_cert_chain |
La lista delimitada por comas de certificados, en orden TLS estándar, de la cadena de certificados de cliente para una conexión mTLS establecida en la que el certificado de cliente pasó la validación, sin incluir el certificado de hoja. La codificación del certificado cumple con RFC 9440. Si el tamaño combinado de |
Limitaciones
La siguiente limitación se aplica a los encabezados personalizados que se usan con balanceadores de cargas regionales:
- No puedes configurar encabezados personalizados en servicios de backend regionales que usan los balanceadores de cargas de aplicaciones externos regionales y los balanceadores de cargas de aplicaciones internos regionales, y los servicios de backend globales que usan los balanceadores de cargas de aplicaciones internos entre regiones.
- Las siguientes variables de encabezado personalizadas no son compatibles con los balanceadores de cargas de aplicaciones externos regionales:
cdn_cache_idcdn_cache_statusclient_region_subdivisionclient_cityclient_city_lat_long