Crea encabezados personalizados en mapas de URL

En esta página, se describe cómo funcionan los encabezados personalizados en los mapas de URL que usan los balanceadores de cargas de aplicaciones externos regionales, los balanceadores de cargas de aplicaciones internos regionales y los balanceadores de cargas de aplicaciones internos entre regiones.

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

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 realiza una solicitud al backend, el balanceador de cargas agrega encabezados de solicitud.
El balanceador de cargas establece los encabezados de respuesta antes de mostrar una respuesta al cliente.

A fin de habilitar los encabezados personalizados para los balanceadores de cargas de aplicaciones externos regionales, los balanceadores de cargas de aplicaciones internos regionales y los balanceadores de cargas de aplicaciones internos entre regiones, especifica una lista de nombres de encabezado y valores de encabezado en el archivo de configuración del mapa de URL.

Los nombres de encabezados deben tener 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.
El nombre del encabezado no debe comenzar con X-Google, X-Goog-, X-GFE ni X-Amz-.
El nombre del encabezado no debe ser Host ni authority. Host y authority son palabras clave especiales que Google Cloud reserva. No puedes modificar estos encabezados para los balanceadores de cargas basados en Envoy. En cambio, te recomendamos que crees otros encabezados personalizados (por ejemplo, MyHost) para que no interfieras en los nombres de los encabezados reservados.
Un nombre de encabezado no debe aparecer más de una vez en la lista de encabezados.

Los nombres de encabezado no distinguen mayúsculas de 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.

Los valores de encabezado tienen las propiedades siguientes:

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 no puede quedar en blanco. Se rechazan los encabezados 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. Para obtener una lista completa de las variables permitidas en el valor del encabezado, consulta Variables que pueden aparecer en el valor del encabezado.

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

Agrega encabezados de solicitud o respuesta

Para agregar encabezados de solicitud o respuesta, usa la CLI de gcloud a fin de editar el mapa de URL de la siguiente manera:

regional

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION

A continuación, se muestra un archivo YAML de muestra que indica cómo usar variables en encabezados personalizados:

   defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
   name: regional-lb-map
   region: region/REGION
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: regions/REGION/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requesteHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name

Ten en cuenta los siguientes comportamientos:

Si el encabezado de respuesta con variables personalizadas se resuelve en una cadena vacía, se quita.
Si el encabezado de una solicitud con variables personalizadas se resuelve en una cadena vacía, se mantiene con un marcador de posición de cadena vacía.
Si un encabezado de solicitud personalizado incluye una variable personalizada, y una solicitud de cliente entrante también incluye el mismo encabezado, el valor del encabezado de solicitud del cliente se reemplazará por el valor nuevo que proporcionó el encabezado del balanceador de cargas.

Variables que pueden aparecer en el valor del encabezado

Las siguientes variables pueden aparecer en los valores de encabezado personalizados.

Variable	Descripción
`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_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_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`.
`origin_request_header`	Refleja el valor del encabezado `Origin` en la solicitud de casos de uso de uso compartido de recursos entre dominios (CORS).
`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

Los valores geográficos 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.

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 agrega la cadena `client_cert_serial_number_exceeded_size_limit` en `client_cert_error`, 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, la cadena `client_cert_spiffe_id_exceeded_size_limit` se agrega a `client_cert_error`.
`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_uri_sans_exceeded_size_limit` se agrega la cadena `client_cert_error` 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, se agrega la cadena `client_cert_dnsname_sans_exceeded_size_limit` en `client_cert_error` 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`	Campo completo de la entidad emisora codificado en Base64 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`	Campo completo del asunto codificado en base64 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 el RFC 9440: el certificado binario DER está codificado con Base64 (sin saltos de línea, espacios ni otros caracteres fuera del alfabeto 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.

Limitaciones

La siguiente limitación se aplica a los encabezados personalizados que se usan con balanceadores de cargas regionales:

No puedes configurar encabezados personalizados en servicios de backend regionales que usan los balanceadores de cargas de aplicaciones externos regionales y los balanceadores de cargas de aplicaciones internos regionales, y los servicios de backend globales que usan los balanceadores de cargas de aplicaciones internos entre regiones.
Las siguientes variables de encabezado personalizadas no son compatibles con los balanceadores de cargas de aplicaciones externos regionales:
- cdn_cache_id
- cdn_cache_status
- client_region_subdivision
- client_city
- client_city_lat_long