Crea encabezados personalizados en servicios de backend

En esta página, se describe cómo configurar encabezados personalizados en servicios de backend que usan los balanceadores de cargas de aplicaciones externos globales.

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.

Importante: Los balanceadores de cargas de aplicaciones externos globales también admiten transformaciones de encabezados en el mapa de URL. Puedes administrar encabezados personalizados en servicios de backend (como se describe en esta página) o en mapas de URL. Las capacidades son similares. Recomendamos colocar las transformaciones de encabezados en el mapa de URL para que todas las transformaciones de encabezados se mantengan en una sola ubicación. Si hay configuraciones de encabezado personalizadas presentes en el mapa de URL y en el servicio de backend, se aplican ambas configuraciones. Sin embargo, si se establece el mismo encabezado en el servicio de backend y en el mapa de URL, el mapa de URL tiene prioridad y se ignora la configuración del servicio de backend. Si deseas obtener un ejemplo basado en mapas de URL, consulta Configura la administración del tráfico para balanceadores de cargas de aplicaciones externos globales.

Antes de comenzar

• Si es necesario, actualiza a la última versión de Google Cloud CLI:

  gcloud components update
  

  Nota: Asegúrate de usar la versión 309.0.0 de la CLI de gcloud o una posterior.

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-IP ni CDN-Loop.
• No se deben usar los siguientes encabezados de salto a salto: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization y Proxy-Authenticate. De acuerdo con la RFC 2616, las cachés no almacenan estos encabezados ni los proxies de destino los propagan.
• El nombre del encabezado no debe comenzar con X-Google, X-Goog-, X-GFE ni X-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

Para crear un servicio de backend con encabezados personalizados, consulta Configura encabezados de solicitud personalizados.

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 Host personalizado si reemplazas un encabezado de solicitud Host existente.
• No puedes configurar un encabezado de respuesta Host personalizado con acciones de encabezado en el mapa de URL. Sin embargo, puedes configurar el encabezado de respuesta Host personalizado en el servicio de backend.
• Además, lo siguiente se aplica a los encabezados de solicitud y respuesta:
  • No puedes agregar ni quitar encabezados Host personalizados.
  • No puedes usar variables con encabezados Host personalizados.

Nota: Anunciamos un cambio en el comportamiento de los encabezados personalizados configurados en mapas de URL y servicios de backend. Este cambio no afecta a los proyectos que tenían tráfico existente que usaba encabezados personalizados antes del 14 de noviembre de 2022. Para obtener más información, consulta la nota de la versión del 14 de noviembre de 2022.

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 encabezado Origin
• 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 con 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 de 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_error se establece en client_cert_spiffe_id_exceeded_size_limit.
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 client_cert_uri_sans. Si client_cert_uri_sans tiene más de 512 bytes, client_cert_error se establece en client_cert_uri_sans_exceeded_size_limit y la lista separada por comas se establece en una string vacía.
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_dnsname_sans tiene más de 512 bytes, client_cert_error se establece en client_cert_dnsname_sans_exceeded_size_limit y la lista separada por comas se establece en una string vacía.
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_issuer_dn tiene más de 512 bytes, la string client_cert_issuer_dn_exceeded_size_limit se agrega a client_cert_error y client_cert_issuer_dn se establece en una string vacía.
client_cert_subject_dn	Codificación DER codificada en Base64 del campo completo del asunto del certificado. Si client_cert_subject_dn tiene más de 512 bytes, la string client_cert_subject_dn_exceeded_size_limit se agrega a client_cert_error y client_cert_subject_dn se establece en una string vacía.
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 DER binario está codificado con Base64 y delimitado por dos puntos en ambos lados. Si client_cert_leaf excede los 16 KB sin codificación, la string client_cert_validated_leaf_exceeded_size_limit se agrega a client_cert_error y client_cert_leaf se configura como una string vacía.
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 client_cert_leaf y client_cert_chain antes de que la codificación en base64 supere los 16 KB, la string client_cert_validated_chain_exceeded_size_limit se agrega a client_cert_error y client_cert_chain se configura como una string vacía.

Configura encabezados de solicitud personalizados

Console

Haz lo siguiente para agregar encabezados de solicitud personalizados a un servicio de backend existente:

1. Dirígete a la página Balanceo de cargas.
   Ir a la página Balanceo de cargas
2. Haz clic en Backends.
3. Haz clic en el nombre de un servicio de backend.
4. Haz clic en Editar .
5. Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
6. En Encabezados de solicitud personalizados, haz clic en Agregar encabezado.
7. Ingresa el nombre del encabezado y el valor del encabezado para el encabezado de la solicitud personalizado.
8. Ingresa cualquier encabezado de solicitud personalizado adicional.
9. Haz clic en Guardar.

Haz lo siguiente para quitar un encabezado de solicitud personalizado de un servicio de backend:

1. Dirígete a la página Balanceo de cargas.
   Ir a la página Balanceo de cargas
2. Haz clic en Backends.
3. Haz clic en el nombre de un servicio de backend.
4. Haz clic en Editar .
5. Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
6. Haz clic en la X junto al nombre del encabezado de solicitud personalizado que deseas quitar.
7. 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:

1. Dirígete a la página Balanceo de cargas.
   Ir a la página Balanceo de cargas
2. Haz clic en Backends.
3. Haz clic en el nombre de un servicio de backend.
4. Haz clic en Editar .
5. Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
6. En Encabezados de respuesta personalizados, haz clic en Agregar encabezado.
7. Ingresa el nombre y el valor del encabezado de respuesta personalizado.
8. Ingresa cualquier encabezado de respuesta personalizado adicional.
9. Haz clic en Guardar.

Sigue estos pasos para quitar un encabezado de respuesta personalizado de un servicio de backend:

1. Dirígete a la página Balanceo de cargas.
   Ir a la página Balanceo de cargas
2. Haz clic en Backends.
3. Haz clic en el nombre de un servicio de backend.
4. Haz clic en Editar .
5. Haz clic en Configuración avanzada (afinidad de sesión, tiempo de espera para el vaciado de conexiones, políticas de seguridad).
6. Haz clic en la X junto al nombre del encabezado de respuesta personalizado que quieres quitar.
7. 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.