Los encabezados de solicitud y respuesta personalizados te permiten especificar encabezados adicionales que el balanceador de carga puede añadir a las solicitudes y respuestas HTTP(S). En función de la información detectada por el balanceador de carga, estos encabezados pueden incluir la siguiente información:
- Latencia al cliente
- Ubicación geográfica de la dirección IP del cliente
- Parámetros de la conexión TLS
Los encabezados de solicitud personalizados se admiten en los servicios de backend, mientras que los encabezados de respuesta personalizados se admiten en los servicios de backend y los segmentos de backend.
El balanceador de carga añade de forma predeterminada determinados encabezados a todas las solicitudes y respuestas HTTP(S) que procesa en el proxy entre los backends y los clientes. Para obtener más información, consulta Proxies de destino.
Encabezados personalizados en mapas de URLs
Los balanceadores de carga de aplicaciones externos globales admiten una función similar para la transformación de encabezados en el mapa de URLs. Aunque puedes gestionar los encabezados personalizados en los servicios backend (como se describe en esta página), te recomendamos que incluyas las transformaciones de encabezados en el mapa de URLs para que todas las transformaciones de encabezados se mantengan en una sola ubicación.
Si hay configuraciones de encabezados personalizados tanto en el mapa de URLs como en el servicio de backend, se aplicarán ambas configuraciones. Sin embargo, si el mismo encabezado se define tanto en el servicio backend como en el mapa de URLs, el mapa de URLs tiene prioridad y se ignora la configuración del servicio backend. Para ver un ejemplo basado en un mapa de URLs, consulta Configurar la gestión del tráfico de los balanceadores de carga de aplicación externos globales.
Antes de empezar
Si es necesario, actualiza a la versión más reciente de la CLI de Google Cloud:
gcloud components update
Cómo funcionan los encabezados personalizados
Los encabezados personalizados funcionan de la siguiente manera:
Cuando el balanceador de carga reenvía una solicitud al backend, añade encabezados de solicitud.
El balanceador de carga añade encabezados de solicitud personalizados solo a las solicitudes de los clientes, no a las comprobaciones del estado. Si tu backend requiere un encabezado específico para la autorización que falta en el paquete de comprobación del estado, es posible que la comprobación del estado falle.
El balanceador de carga define los encabezados de respuesta antes de devolver las respuestas al cliente.
Para habilitar los encabezados personalizados, especifica una lista de encabezados en una propiedad del servicio de backend o del segmento de backend.
Cada encabezado se especifica como una cadena header-name:header-value. El encabezado debe
contener dos puntos que separen el nombre y el valor del encabezado.
Los nombres de los encabezados deben cumplir los siguientes requisitos:
- El nombre del encabezado debe ser una definición de nombre de campo de encabezado HTTP válida (según el RFC 7230).
- El encabezado
Hostse puede configurar, pero está sujeto a ciertas limitaciones. - El nombre del encabezado no puede ser
authority. Se trata de una palabra clave especial reservada porGoogle Cloud. No puedes modificar este encabezado en balanceadores de carga basados en Envoy, como el balanceador de carga de aplicación externo global. En su lugar, te recomendamos que crees otros encabezados personalizados para no interferir con los nombres de encabezados reservados. - El nombre del encabezado no puede ser
X-User-IPniCDN-Loop. - No se deben usar los siguientes encabezados de salto a salto:
Keep-Alive,Transfer-Encoding,TE,Connection,TraileryUpgrade. De acuerdo con el RFC 2616, las cachés no almacenan estos encabezados ni los proxies de destino los propagan. - El nombre del encabezado no debe empezar por
X-Google,X-Goog-,X-GFEniX-Amz-. - Un nombre de encabezado no puede aparecer más de una vez en la lista de encabezados añadidos.
Los valores de los encabezados deben cumplir los siguientes requisitos:
- El valor del encabezado debe ser una definición de campo de encabezado HTTP válida según el RFC 7230 (no se permiten formas obsoletas).
- El valor de la cabecera puede estar en blanco.
- El valor del encabezado puede incluir una o varias variables entre llaves que abarquen los valores que proporciona el balanceador de carga. En la siguiente sección se incluye una lista de las variables permitidas en el valor del encabezado.
La herramienta de línea de comandos gcloud tiene una marca para especificar
encabezados de solicitud, que es --custom-request-header. Asegúrate de incluir el nombre y el valor del encabezado entre comillas simples rectas (') con esta marca.
El formato general de la marca es el siguiente:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
A continuación, se muestra un ejemplo de un valor de encabezado con dos variables, client_region y client_city, entre llaves.
--custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'
En el caso de los clientes ubicados en Mountain View (California), el balanceador de carga añade un encabezado de la siguiente manera:
X-Client-Geo-Location:US,Mountain View
Encabezados de host
Se aplican las siguientes limitaciones al configurar un encabezado Host personalizado
con un balanceador de carga de aplicación externo global:
- Solo puedes configurar un encabezado de solicitud
Hostpersonalizado si sustituyes un encabezado de solicitudHost. - No puedes configurar un encabezado de respuesta
Hostpersonalizado mediante acciones de encabezado en el mapa de URLs. Sin embargo, puedes configurar el encabezado de respuesta personalizadoHosten el servicio de backend. - Además, se aplican los siguientes requisitos a los encabezados de solicitud y de respuesta:
- No puedes añadir ni quitar encabezados
Hostpersonalizados. - No puedes usar variables con encabezados
Hostpersonalizados.
- No puedes añadir ni quitar encabezados
Variables admitidas con valores de encabezado
Las siguientes variables pueden aparecer en los valores de encabezado personalizados.
| Variable | Descripción |
|---|---|
cdn_cache_id |
Código e ID de la instancia de caché utilizada para atender la solicitud.
Es el mismo valor que se rellena en el campo jsonPayload.cacheId de los registros de solicitudes de Cloud CDN en Logging.
|
cdn_cache_status |
Estado actual de la caché. Los valores pueden ser hit,
miss, revalidated, stale,
uncacheable o disabled para cualquier objeto
servido por un backend habilitado para Cloud CDN.
|
origin_request_header |
Refleja el valor del encabezado Origin de la solicitud
en los casos prácticos de uso compartido de recursos entre dominios (CORS).
|
client_rtt_msec |
Tiempo de transmisión de ida y vuelta estimado entre el balanceador de carga y el cliente HTTP(S), en milisegundos. Es el parámetro de tiempo de ida y vuelta suavizado (SRTT) medido por la pila TCP del balanceador de carga, según el RFC 2988. El RTT suavizado es un algoritmo que gestiona las variaciones y las anomalías que pueden producirse en las mediciones de RTT. |
client_region |
El país (o la región) asociado a la dirección IP del cliente. Es un código de región Unicode CLDR, como US o FR. En la mayoría de los países, estos códigos se corresponden directamente con los códigos ISO-3166-2.
|
client_region_subdivision |
Subdivisión, por ejemplo, una provincia o un estado, del país asociado a la dirección IP del cliente. Es un ID de subdivisión CLDR de Unicode, como USCA o CAON. Estos códigos Unicode se derivan de las subdivisiones definidas en el estándar ISO-3166-2.
|
client_city |
Nombre de la ciudad desde la que se ha originado la solicitud. Por ejemplo,
Mountain View para Mountain View (California). No hay una lista canónica de valores válidos para esta variable. Los nombres de las ciudades pueden contener letras, números y espacios US-ASCII, así como los siguientes caracteres:
!#$%&'*+-.^_`|~.
|
client_city_lat_long |
Latitud y longitud de la ciudad desde la que se ha originado la solicitud. Por ejemplo, 37.386051,-122.083851 para una solicitud de Mountain View.
|
client_ip_address |
La dirección IP del cliente. Por lo general, se trata de la misma dirección IP de cliente que la penúltima dirección del encabezado X-Forwarded-For, a menos que el cliente utilice un proxy o que se haya manipulado el encabezado X-Forwarded-For. |
client_port |
Puerto de origen del cliente. |
client_encrypted |
true si la conexión entre el cliente y el balanceador de carga está cifrada (con HTTPS, HTTP/2 o HTTP/3); de lo contrario, false.
|
client_protocol |
El protocolo HTTP que se usa para la comunicación entre el cliente y el balanceador de carga. Uno de los valores HTTP/1.0, HTTP/1.1, HTTP/2 o HTTP/3.
|
device_request_type |
El dispositivo del cliente, derivado de los valores del encabezado
Estos son los valores posibles:
|
server_ip_address |
La dirección IP del balanceador de carga al que se conecta el cliente. Esto puede ser útil cuando varios balanceadores de carga comparten backends comunes. Es lo mismo que la última dirección IP de la
encabezado X-Forwarded-For.
|
server_port |
Número de puerto de destino al que se conecta el cliente. |
tls_sni_hostname |
Indicación del nombre del servidor (tal como se define en el RFC 6066), si el cliente la proporciona durante el handshake TLS o QUIC. El nombre de host se convierte a minúsculas y se elimina cualquier punto final. |
tls_version |
Versión de TLS negociada entre el cliente y el balanceador de carga durante el handshake de SSL. Entre los valores posibles se incluyen TLSv1,
TLSv1.1, TLSv1.2 y TLSv1.3. Si el cliente se conecta mediante QUIC en lugar de TLS, el valor es QUIC.
|
tls_cipher_suite |
Conjunto de cifrado negociado durante el handshake TLS. El valor es un número hexadecimal de cuatro dígitos definido por el registro de conjuntos de cifrado TLS de IANA. Por ejemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor está vacío en el caso de QUIC y de las conexiones de cliente sin cifrar.
|
tls_ja3_fingerprint |
JA3 Huella digital TLS/SSL si el cliente se conecta mediante HTTPS, HTTP/2 o HTTP/3. |
tls_ja4_fingerprint |
JA4 Huella digital TLS/SSL si el cliente se conecta mediante HTTPS, HTTP/2 o HTTP/3. |
user_agent_family |
El tipo de navegador del cliente, derivado de los valores del encabezado
Estos son los valores posibles:
|
El balanceador de carga expande las variables a cadenas vacías cuando no puede determinar sus valores. Por ejemplo:
- Variables de ubicación geográfica cuando se desconoce la ubicación de la dirección IP
- Parámetros de TLS cuando no se usa TLS
- El
{origin_request_header}cuando la solicitud no incluye un encabezadoOrigin - El encabezado
{cdn_cache_status}cuando se incluye en un encabezado de solicitud
Los valores geográficos (regiones, subdivisiones y ciudades) 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. Aunque el encabezado X-Forwarded-For original contenga 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 que contienen los paquetes recibidos por el balanceador de carga.
Los encabezados que añade el balanceador de carga sobrescriben los encabezados que ya tengan el mismo nombre. En los nombres de los encabezados no se distingue entre mayúsculas y minúsculas. Cuando se transfieren nombres de encabezados a un backend HTTP/2, el protocolo HTTP/2 codifica los nombres de los encabezados en minúsculas.
En los valores de encabezado, los espacios iniciales y finales no son significativos y no se transfieren al backend. Para permitir el uso de llaves en los valores de los encabezados, el balanceador de carga interpreta dos llaves de apertura ({{) como una sola llave de apertura ({) y dos llaves de cierre (}}) como una sola llave de cierre (}).
Encabezados personalizados de TLS mutuo
Las siguientes variables de encabezado adicionales están disponibles si se configura TLS mutuo (mTLS) en TargetHttpsProxy del balanceador de carga.
| Variable | Descripción |
|---|---|
client_cert_present |
true si el cliente ha proporcionado un certificado durante el handshake TLS; de lo contrario, false.
|
client_cert_chain_verified |
true si la cadena de certificados de cliente se verifica con un TrustStore configurado; de lo contrario, false.
|
client_cert_error |
Cadenas predefinidas que representan las condiciones de error. Para obtener más información sobre las cadenas de error, consulta Modos de validación de clientes de mTLS. |
client_cert_sha256_fingerprint |
Huella digital SHA-256 codificada en Base64 del certificado de cliente. |
client_cert_serial_number |
Número de serie del certificado de cliente.
Si el número de serie tiene más de 50 bytes, client_cert_error
se define como client_cert_serial_number_exceeded_size_limit y el número de serie se define como una cadena vacía. |
client_cert_spiffe_id |
El ID de SPIFFE del campo de nombre alternativo del sujeto (SAN). Si el valor no es válido o supera los 2048 bytes, el ID de SPIFFE se define como una cadena vacía. Si el ID de SPIFFE tiene más de 2048 bytes, |
client_cert_uri_sans |
Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo URI.
Las extensiones SAN se extraen del certificado de cliente.
El ID de SPIFFE no se incluye en el campo Si el |
client_cert_dnsname_sans |
Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo DNSName. Las extensiones SAN se extraen del certificado de cliente. Si el |
client_cert_valid_not_before |
Marca de tiempo (cadena de fecha en formato RFC 3339
) anterior a 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 (cadena de fecha en formato RFC 3339) tras la cual el certificado de cliente no es válido.
Por ejemplo, 2022-07-01T18:05:09+00:00.
|
client_cert_issuer_dn |
Codificación DER codificada en Base64 del campo Issuer completo del certificado. Si |
client_cert_subject_dn |
Codificación DER codificada en Base64 del campo Subject completo del certificado. Si |
client_cert_leaf |
El certificado de hoja de cliente de una conexión mTLS establecida en la que el certificado ha superado la validación. La codificación de certificados cumple la normativa RFC 9440. Esto significa que el certificado DER binario se codifica con Base64 y se delimita con dos puntos a cada lado. Si |
client_cert_chain |
Lista de certificados separados por comas, en orden TLS estándar, de la cadena de certificados de cliente de una conexión mTLS establecida en la que el certificado de cliente ha superado la validación, sin incluir el certificado de hoja. La codificación de certificados cumple el estándar RFC 9440. Si el tamaño combinado de |
Configurar encabezados de solicitud personalizados
Consola
Para añadir encabezados de solicitud personalizados a un servicio de backend, sigue estos pasos:
- Ve a la página de resumen de balanceo de carga.
Ir a la página Balanceo de carga - Haz clic en Back-ends.
- Haz clic en el nombre de un servicio backend.
- Haz clic en Editar .
- Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
- En Encabezados de solicitud personalizados, haz clic en Añadir encabezado.
- Introduce el nombre de la cabecera y el valor de la cabecera de la cabecera de solicitud personalizada.
- Introduce los encabezados de solicitud personalizados adicionales.
- Haz clic en Guardar.
Para quitar un encabezado de solicitud personalizado de un servicio de backend, sigue estos pasos:
- Ve a la página de resumen de balanceo de carga.
Ir a la página Balanceo de carga - Haz clic en Back-ends.
- Haz clic en el nombre de un servicio backend.
- Haz clic en Editar .
- Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
- Haz clic en la X situada junto al nombre del encabezado de solicitud personalizado que quieras quitar.
- Haz clic en Guardar.
gcloud
Para especificar encabezados de solicitud personalizados, usa el comando gcloud compute backend-services
create o gcloud compute backend-services
update con la marca --custom-request-header.
Para crear un servicio de backend con encabezados de solicitud personalizados, sigue estos pasos:
gcloud 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]'
Para añadir más encabezados de solicitud, especifica un nombre y un valor únicos para cada encabezado repitiendo la marca --custom-request-header.
Para añadir encabezados personalizados a un servicio de backend, sigue estos pasos:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
--custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'
En el paso anterior, se sustituyen los encabezados que ya estén en el servicio backend por los encabezados de solicitud que especifiques en el comando.
Para quitar todos los encabezados de un servicio de backend, sigue estos pasos:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--no-custom-request-headers
API
Haz una solicitud PATCH al método backendServices.patch:
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME "customRequestHeaders": [ "client_city:Mountain View" ]
Configurar encabezados de respuesta personalizados
Consola
Para añadir encabezados de respuesta personalizados a un servicio de backend, sigue estos pasos:
- Ve a la página de resumen de balanceo de carga.
Ir a la página Balanceo de carga - Haz clic en Back-ends.
- Haz clic en el nombre de un servicio backend.
- Haz clic en Editar .
- Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
- En Encabezados de respuesta personalizados, haz clic en Añadir encabezado.
- Introduce el nombre de la cabecera y el valor de la cabecera de la cabecera de respuesta personalizada.
- Introduce los encabezados de respuesta personalizados adicionales que quieras.
- Haz clic en Guardar.
Para quitar un encabezado de respuesta personalizado de un servicio de backend, sigue estos pasos:
- Ve a la página de resumen de balanceo de carga.
Ir a la página Balanceo de carga - Haz clic en Back-ends.
- Haz clic en el nombre de un servicio backend.
- Haz clic en Editar .
- Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
- Haz clic en la X situada junto al nombre del encabezado de respuesta personalizado que quieras quitar.
- Haz clic en Guardar.
gcloud
En el caso de los servicios de backend, usa el comando gcloud compute backend-services
create o gcloud compute backend-services
update con la marca --custom-response-header.
En el caso de los segmentos de backend, usa el comando gcloud compute backend-buckets
create o gcloud compute backend-buckets
update con la marca --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]'
Ejemplo con el encabezado X-Frame-Options:
gcloud compute backend-buckets update gaming-lab \
--custom-response-header='X-Frame-Options: DENY'
Ejemplo con el encabezado Strict-Transport-Security:
En el siguiente ejemplo se muestra cómo añadir un encabezado de respuesta personalizado para admitir la seguridad de transporte estricta mediante HTTP (HSTS):
gcloud compute backend-services update customer-bs-name \
--global \
--custom-response-header='Strict-Transport-Security: max-age=63072000'
API
En el caso de los segmentos de backend, usa la llamada a la API Method: backendBuckets.insert o Method: backendBuckets.update.
En el caso de los servicios de backend, usa la llamada a la API Method: backendServices.insert o Method: backendServices.update.
Usa una de las siguientes llamadas a la API:
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
Añade el siguiente fragmento al cuerpo de la solicitud JSON:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Definir encabezados de respuesta para Cloud Storage
Si necesitas definir encabezados HTTP en las respuestas de Cloud Storage (por ejemplo, encabezados de política de recursos entre orígenes, X-Frame-Options o X-XSS-Protection),Google Cloud te ofrece la opción de usar encabezados personalizados para Cloud CDN con Cloud Storage. Para ello, configure encabezados personalizados a nivel de contenedor backend del balanceador de carga, tal como se describe en esta página.
Los encabezados de respuesta personalizados configurados a nivel de contenedor de backend solo se añaden a las respuestas si la solicitud del cliente se envía a la dirección IP del balanceador de carga. Los encabezados personalizados no se añaden a las respuestas si la solicitud del cliente se ha enviado directamente a la API Cloud Storage.
Usar encabezados personalizados con Google Cloud Armor
Cuando configuras una política de seguridad de Cloud Armor, puedes configurar Cloud Armor para que inserte un encabezado y un valor personalizados. Si tu política de seguridad de Cloud Armor está configurada para insertar el mismo nombre de encabezado personalizado que los encabezados personalizados de tu balanceador de carga de aplicaciones externo global o de tu balanceador de carga de aplicaciones clásico, el valor del encabezado especificado en tu política de seguridad de Cloud Armor se sobrescribe con el valor rellenado por el balanceador de carga. Si no quieres que se sobrescriba la política de Cloud Armor, asegúrate de no usar el mismo nombre.
Limitaciones
Las siguientes limitaciones se aplican a los encabezados personalizados que se usan con los balanceadores de carga globales:
- El tamaño total de todos los encabezados de solicitud personalizados (con el nombre y el valor combinados, antes de la expansión de variables) de cada servicio de backend no debe superar los 8 KB ni los 16 encabezados de solicitud.
- El tamaño total de todos los encabezados de respuesta personalizados (con el nombre y el valor combinados, antes de la expansión de variables) de cada servicio de backend no debe superar los 8 KB ni los 16 encabezados de respuesta.