Crea encabezados personalizados en servicios de backend

En esta página, se describe cómo configurar encabezados personalizados en servicios de backend que usa el balanceador de cargas de aplicaciones clásico.

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 de aplicaciones externo global realiza una solicitud al backend, el balanceador de cargas agrega encabezados de solicitud.

  • El balanceador de cargas de aplicaciones externo global configura 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 encabezado 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 RFC 7230).
  • El nombre del encabezado no debe ser X-User-IP ni CDN-Loop.
  • No se deben usar los siguientes encabezados de salto por salto: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization y Proxy-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-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 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.

Por ejemplo, puedes especificar un encabezado con dos nombres de variable: uno para la región y otro para la ciudad del cliente. La herramienta de línea de comandos de gcloud tiene --custom-request-header, una marca para especificar encabezados de solicitudes. Asegúrate de usar solo comillas rectas (') con esta marca.

Este es el formato general para la marca:

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Las variables deben incluirse entre llaves. Por ejemplo:

    --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

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 (p. ej., 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. Esta es la misma que la dirección IP de cliente que es la próxima y última en el encabezado X-Forwarded-For.
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.

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_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 del asunto completo 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 binario DER está codificado con Base64 y delimitado por dos puntos en cada lado.

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

Consola

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"
]

Terraform

Para ver una secuencia de comandos de Terraform que crea un balanceador de cargas con encabezados personalizados, consulta Ejemplos de Terraform para balanceadores de cargas de aplicaciones externos globales.

Configura encabezados de respuesta personalizados

Consola

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]

Terraform

Para ver una secuencia de comandos de Terraform que crea un balanceador de cargas con encabezados personalizados, consulta Ejemplos de Terraform para balanceadores de cargas de aplicaciones externos globales.

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:

  • Puedes especificar un máximo de 16 encabezados de solicitud personalizados para cada servicio de backend.
  • Puedes especificar un máximo de 16 encabezados de respuesta personalizados para cada servicio de backend.
  • El tamaño total de todos los encabezados de solicitud personalizados por servicio de backend (nombre y valor combinados, antes de la expansión variable) no puede exceder los 8 KB.
  • El tamaño total de todos los encabezados de respuesta personalizados por servicio de backend (nombre y valor combinados, antes de la expansión variable) no puede exceder los 8 KB.

¿Qué sigue?