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
Los encabezados de solicitud personalizados son compatibles con los servicios de backend, mientras que los encabezados de respuesta personalizados son compatibles con servicios de backend y depósitos de backend.
El balanceador de cargas agrega ciertos encabezados de forma predeterminada a todas las solicitudes y respuestas HTTP(S) que envía a través de proxies entre los backends y los clientes. Para obtener más información, consulta Proxies de destino.
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 reenvía una solicitud al backend, el balanceador de cargas agrega encabezados de solicitud.
El balanceador de cargas agrega encabezados de solicitud personalizados solo a las solicitudes del cliente, no a los sondeos de verificación de estado. Si el backend requiere un encabezado específico para la autorización que falta en el paquete de verificación de estado, la verificación de estado puede fallar.
El balanceador de cargas establece los encabezados de respuesta antes de mostrar las respuestas al cliente.
Para habilitar los encabezados personalizados, debes especificar una lista de encabezados en una propiedad del servicio de backend o del bucket de backend.
Debes especificar cada encabezado como una string header-name:header-value. El encabezado debe contener dos puntos que separen el nombre del encabezado y su valor.
Los nombres de encabezados deben cumplir con los siguientes requisitos:
- El nombre del encabezado debe ser una definición de nombre de campo de encabezado HTTP válida (según RFC 7230).
- Se puede configurar el encabezado
Host, pero está sujeto a ciertas limitaciones. - El nombre del encabezado no debe ser
authority. Esta es una palabra clave especial reservada por Google Cloud. No puedes modificar este encabezado para los balanceadores de cargas basados en Envoy, como el balanceador de cargas de aplicaciones externo global. En cambio, te recomendamos que crees otros encabezados personalizados para no interferir en los nombres de encabezados reservados. - El nombre del encabezado no debe ser
X-User-IPniCDN-Loop. - No se deben usar los siguientes encabezados de salto por salto:
Keep-Alive,Transfer-Encoding,TE,Connection,Trailer,Upgrade,Proxy-AuthorizationyProxy-Authenticate. De acuerdo con RFC 2616, estos encabezados no se almacenan en cachés ni se propagan mediante los proxies de destino. - El nombre del encabezado no debe comenzar con
X-Google,X-Goog-,X-GFEniX-Amz-. - Un nombre de encabezado no debe aparecer más de una vez en la lista de encabezados agregados.
Los valores de encabezado deben cumplir con los siguientes requisitos:
- 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 puede estar 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. En la sección siguiente, se muestra una lista de las variables permitidas en el valor del encabezado.
La herramienta de línea de comandos de gcloud tiene la marca --custom-request-header para especificar encabezados de solicitudes. Asegúrate de encerrar el nombre y el valor del encabezado entre comillas simples (') con esta marca.
Este es el formato general para la marca:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
El siguiente es un ejemplo de un valor de encabezado con dos variables, client_region y client_city, encerradas entre llaves.
--custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'
Para los clientes ubicados en Mountain View, California, el balanceador de cargas agrega un encabezado de la manera siguiente:
X-Client-Geo-Location:US,Mountain View
Encabezados de host
Las siguientes limitaciones se aplican cuando configuras un encabezado Host personalizado con un balanceador de cargas de aplicaciones externo global:
- Solo puedes configurar un encabezado de solicitud
Hostpersonalizado si reemplazas un encabezado de solicitudHostexistente. - No puedes configurar un encabezado de respuesta
Hostpersonalizado con acciones de encabezado en el mapa de URL. Sin embargo, aún puedes configurar el encabezado de respuesta personalizadoHosten el servicio de backend. - Además, se aplica lo siguiente a los encabezados de solicitud y respuesta:
- No puedes agregar ni quitar encabezados
Hostpersonalizados. - No puedes usar variables con encabezados
Hostpersonalizados.
- No puedes agregar ni quitar encabezados
Variables compatibles con valores de encabezado
Las siguientes variables pueden aparecer en los valores de encabezado personalizados.
| Variable | Descripción |
|---|---|
| cdn_cache_id | Código de ubicación e ID de la instancia de caché que se usa para entregar la solicitud.
Este es el mismo valor propagado en el campo jsonPayload.cacheId de los registros de solicitud 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 que entregue un backend habilitado de Cloud CDN.
|
| origin_request_header | Refleja el valor del encabezado Origin en la solicitud de casos de uso de uso compartido de recursos entre dominios (CORS).
|
| 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_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_region_subdivision | Subdivisión, por ejemplo, una provincia o un estado del país asociado a la dirección IP del cliente. Este es un ID de subdivisión CLDR de Unicode, como USCA o CAON. (Estos códigos Unicode se derivan de las subdivisiones definidas por el estándar ISO-3166-2).
|
| client_city | Nombre de la ciudad desde la que se originó 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, espacios y los siguientes caracteres de US-ASCII: !#$%&'*+-.^_`|~.
|
| client_city_lat_long | La latitud y longitud de la ciudad en la que se originó 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, 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.
|
| 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- 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. 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.
Los encabezados que agrega el balanceador de cargas reemplazan los encabezados existentes con el mismo nombre. Los nombres de encabezado no distinguen entre mayúsculas y 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.
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 (}).
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 establece client_cert_error en client_cert_serial_number_exceeded_size_limit, 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, |
| 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 | Codificación DER codificada en base64 del campo completo de la entidad emisora del certificado. Si |
| client_cert_subject_dn | Codificación DER codificada en base64 del campo del asunto completo 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 RFC 9440. Esto significa que el certificado binario DER está codificado con Base64 y delimitado por dos puntos en cada lado. 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 |
Configura encabezados de solicitud personalizados
Console
Haz lo siguiente para agregar encabezados de solicitud personalizados a un servicio de backend existente:
- Dirígete a la página Balanceo de cargas.
Ir a la página Balanceo de cargas - Haz clic en Backends.
- Haz clic en el nombre de un servicio de backend.
- Haz clic en Editar .
- Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
- En Encabezados de solicitud personalizados, haz clic en Agregar encabezado.
- Ingresa el nombre del encabezado y el valor del encabezado para el encabezado de la solicitud personalizado.
- Ingresa cualquier encabezado de solicitud personalizado adicional.
- Haz clic en Guardar.
Haz lo siguiente para quitar un encabezado de solicitud personalizado de un servicio de backend:
- Dirígete a la página Balanceo de cargas.
Ir a la página Balanceo de cargas - Haz clic en Backends.
- Haz clic en el nombre de un servicio de backend.
- Haz clic en Editar .
- Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
- Haz clic en la X junto al nombre del encabezado de solicitud personalizado que deseas 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.
Crea un servicio de backend con encabezados de solicitud personalizados:
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 agregar más encabezados de solicitudes, especifica un nombre y un valor de encabezado únicos con la marca --custom-request-header.
Agrega encabezados personalizados a un servicio de backend existente:
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]'
El paso anterior reemplaza cualquier encabezado que ya esté en el servicio de backend por los encabezados de solicitud que especifiques en el comando.
Usa este comando para quitar todos los encabezados de un servicio de backend:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--no-custom-request-headers
API
Realiza 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" ]
Configura encabezados de respuesta personalizados
Console
Sigue estos pasos para agregar encabezados de respuesta personalizados a un servicio de backend existente:
- Dirígete a la página Balanceo de cargas.
Ir a la página Balanceo de cargas - Haz clic en Backends.
- Haz clic en el nombre de un servicio de backend.
- Haz clic en Editar .
- Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
- En Encabezados de respuesta personalizados, haz clic en Agregar encabezado.
- Ingresa el nombre y el valor del encabezado de respuesta personalizado.
- Ingresa cualquier encabezado de respuesta personalizado adicional.
- Haz clic en Guardar.
Sigue estos pasos para quitar un encabezado de respuesta personalizado de un servicio de backend:
- Dirígete a la página Balanceo de cargas.
Ir a la página Balanceo de cargas - Haz clic en Backends.
- Haz clic en el nombre de un servicio de backend.
- Haz clic en Editar .
- Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
- Haz clic en la X junto al nombre del encabezado de respuesta personalizado que quieres quitar.
- Haz clic en Guardar.
gcloud
Para los servicios de backend, usa el comando gcloud compute backend-services
create o gcloud compute backend-services
update con la marca --custom-response-header.
Para los buckets 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 encabezado X-Frame-Options:
gcloud compute backend-buckets update gaming-lab \
--custom-response-header='X-Frame-Options: DENY'
Ejemplo con encabezado Strict-Transport-Security:
En el siguiente ejemplo, se muestra cómo agregar un encabezado de respuesta personalizado para admitir HTTP con Seguridad de Transporte Estricta (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 buckets de backend, usa la llamada a la API Method: backendBuckets.insert o Method: backendBuckets.update.
Para 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
Agrega el siguiente fragmento al cuerpo de solicitud JSON:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Configura encabezados de respuesta para Cloud Storage
Si necesitas configurar encabezados HTTP en las respuestas de Cloud Storage, como en la política de recursos multiorigen o en los encabezados X-Frame-Options o X-XSS-Protection, Google Cloud te permite utilizar encabezados personalizados de Cloud CDN con Cloud Storage. Para hacerlo, configura los encabezados personalizados a nivel del bucket de backend del balanceador de cargas, como se describe en esta página.
Los encabezados de respuesta personalizados configurados en el nivel del bucket de backend solo se agregan a las respuestas si la solicitud del cliente se envía a la dirección IP del balanceador de cargas. Los encabezados personalizados no se agregan a las respuestas si la solicitud del cliente se realizó directamente a la API de Cloud Storage.
Usa encabezados personalizados con Google Cloud Armor
Cuando configuras una política de seguridad de Google Cloud Armor, puedes configurar Google Cloud Armor para insertar un encabezado y un valor personalizados. Si tu política de seguridad de Google Cloud Armor está configurada para insertar el mismo nombre de encabezado personalizado que los encabezados personalizados del balanceador de cargas de aplicaciones externo global o del balanceador de cargas de aplicaciones clásico, entonces el valor del encabezado especificado en Google Cloud Armor la política de seguridad se reemplaza por el valor propagado por el balanceador de cargas. Si no quieres que se reemplace la política de Google Cloud Armor, asegúrate de no usar el mismo nombre.
Limitaciones
Las siguientes limitaciones se aplican a encabezados personalizados que se usan con balanceadores de cargas globales:
- El tamaño total de todos los encabezados de solicitud personalizados (nombre y valor combinados, antes de la expansión de variables) para cada servicio de backend no debe exceder los 8 KB o 16 encabezados de solicitud.
- El tamaño total de todos los encabezados de respuesta personalizados (nombre y valor combinados, antes de la expansión de variables) para cada servicio de backend no debe exceder los 8 KB o 16 encabezados de respuesta.