Crear encabezados personalizados

Los encabezados de solicitud y respuesta personalizados te permiten especificar encabezados adicionales que el balanceador de cargas de HTTP(S) externo agrega a las solicitudes y respuestas. Estos encabezados pueden incluir información que el balanceador de cargas detecta sobre la conexión del cliente, incluida su latencia, la ubicación geográfica de la dirección IP del cliente y los 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 balanceo de cargas de HTTP(S) 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 del SDK de Cloud:

    gcloud components update
    

Cómo funcionan los encabezados personalizados

Los encabezados personalizados funcionan de la siguiente manera:

  • Cuando el balanceador de cargas de HTTP(S) externo realiza una solicitud al backend, el balanceador de cargas agrega encabezados de solicitud.

  • El balanceador de cargas de HTTP(S) externo configura los encabezados de respuesta antes de mostrar las respuestas al cliente.

Los encabezados de solicitud y respuesta no influyen en el comportamiento del almacenamiento en caché ni en el balanceador de cargas.

Para habilitar los encabezados personalizados, debes especificar una lista de encabezados en una propiedad del servicio de backend o del depósito 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 un encabezado tienen 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 ni CDN-Loop.
  • El nombre del encabezado no debe comenzar con X-Google, X-Goog-, X-GFE ni X-Amz-.
  • El nombre de un encabezado no debe aparecer más de una vez en la lista de encabezados agregados.

Los valores de encabezado tienen las siguientes propiedades:

  • 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 del cliente y otro para su ciudad. La herramienta de línea de comandos de gcloud tiene --custom-request-header, una marca para especificar encabezados de solicitudes. 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

Este es el formato general para la marca:

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

Los valores del encabezado deben incluirse entre llaves. Por ejemplo:

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

Usa solo comillas rectas (') en este comando.

Variables que pueden aparecer en el valor del 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.
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.
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 algoritmo 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.

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 (}).

Trabaja con 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 de resumen del 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 de resumen del 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

Crea un servicio de backend con encabezados de solicitud personalizados:

gcloud beta 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 beta compute backend-services update BACKEND_SERVICE_NAME \
  --global \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

Ten en cuenta que lo anterior reemplaza todo encabezado que ya esté en el servicio de backend con los encabezados de solicitud que especifiques en el comando.

Usa este comando para quitar todos los encabezados de un servicio de backend:

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

Trabaja con 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 de resumen del 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 de resumen del 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

En los servicios de backend, usa el comando gcloud beta compute backend-services create o gcloud beta compute backend-services update con la marca --custom-response-header.

En los depósitos de backend, usa el comando gcloud beta compute backend-buckets create o gcloud beta compute backend-buckets update con la marca --custom-response-header.

gcloud beta compute backend-services (create | update) BACKEND_SERVICE_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'
gcloud beta compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

Ejemplo:

gcloud beta compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

API

En los depósitos de backend, usa la llamada a la API Method: backendBuckets.insert o Method: backendBuckets.update.

En 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/beta/projects/PROJECT_ID/global/backendBuckets

PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices

PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME

Agrega el siguiente fragmento al cuerpo de la solicitud JSON:

"cdnPolicy": {
  "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.

Limitaciones

Las siguientes limitaciones se aplican a los encabezados personalizados:

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

Próximos pasos