Esta página se ha traducido con Cloud Translation API.

Crear encabezados personalizados en mapas de URLs

En esta página se describe cómo funcionan los encabezados personalizados en los mapas de URLs que usan los balanceadores de carga de aplicaciones externos regionales.

Los encabezados de solicitud y respuesta personalizados te permiten especificar encabezados adicionales que el balanceador de carga puede añadir a las solicitudes y respuestas HTTP(S). En función de la información que detecte el balanceador de carga, estos encabezados pueden incluir la siguiente información:

Latencia al cliente
Parámetros de la conexión TLS
Ubicación geográfica de la dirección IP del cliente

Antes de empezar

Si es necesario, actualiza a la versión más reciente de la CLI de Google Cloud:

gcloud components update

Cómo funcionan los encabezados personalizados

Los encabezados personalizados funcionan de la siguiente manera:

Cuando el balanceador de carga envía una solicitud al backend, añade encabezados de solicitud.

El balanceador de carga añade encabezados de solicitud personalizados solo a las solicitudes de los clientes, no a las comprobaciones del estado. Si tu backend requiere un encabezado específico para la autorización que falta en el paquete de comprobación del estado, es posible que la comprobación del estado falle.
El balanceador de carga define los encabezados de respuesta antes de devolver una respuesta al cliente.

Para habilitar encabezados personalizados en balanceadores de carga de aplicaciones externos regionales, especifica una lista de nombres y valores de encabezado en el archivo de configuración del mapa de URLs.

Los nombres de encabezado 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 el RFC 7230.
El nombre del encabezado no puede ser X-User-IP.
El nombre del encabezado no debe empezar por X-Google, X-Goog-, X-GFE ni X-Amz-.
No se deben usar los siguientes encabezados de salto a salto: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer y Upgrade. De acuerdo con el RFC 2616, las cachés no almacenan estos encabezados ni los proxies de destino los propagan.
El nombre del encabezado no puede ser Host ni authority. Tanto Host como authority son palabras clave especiales reservadas por Google Cloud. No puedes modificar estos encabezados en los balanceadores de carga basados en Envoy. En su lugar, te recomendamos que crees otros encabezados personalizados (por ejemplo, MyHost) para no interferir con los nombres de encabezado reservados.
Un nombre de encabezado no puede aparecer más de una vez en la lista de encabezados.

Los nombres de los encabezados no distinguen entre mayúsculas y minúsculas. Cuando los nombres de los encabezados se transfieren a un backend HTTP/2, el protocolo HTTP/2 codifica los nombres de los encabezados en minúsculas.

Los valores de encabezado deben tener las siguientes propiedades:

El valor del encabezado debe ser una definición de campo de encabezado HTTP válida según el RFC 7230. No se permiten formas obsoletas.
El valor de la cabecera no puede estar en blanco. Los encabezados en blanco se rechazan.
El valor del encabezado puede incluir una o varias variables entre llaves que abarquen los valores que proporciona el balanceador de carga. Para obtener una lista completa de las variables permitidas en el valor del encabezado, consulta el artículo Variables que pueden aparecer en el valor del encabezado.

En los valores de las cabeceras, los espacios iniciales y finales no son significativos y no se transfieren al backend. Para permitir el uso de llaves en los valores de los encabezados, el balanceador de carga interpreta dos llaves de apertura ({{) como una sola llave de apertura ({) y dos llaves de cierre (}}) como una sola llave de cierre (}).

Añadir encabezados de solicitud o respuesta

Para añadir encabezados de solicitud o respuesta, usa gcloud CLI para editar el mapa de URLs de la siguiente manera:

Regional

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

A continuación, se muestra un archivo YAML de ejemplo que explica 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
                 requestHeadersToRemove:
                 - 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 un encabezado de respuesta con variables personalizadas se resuelve como una cadena vacía, se elimina.
Si un encabezado de solicitud con variables personalizadas se resuelve en una cadena vacía, se conserva 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 sustituirá por el nuevo valor proporcionado por el encabezado personalizado del balanceador de carga.

Variables que pueden aparecer en el valor de la cabecera

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

Variable	Descripción
`client_region`	El país (o la región) asociado a la dirección IP del cliente. Es un código de región Unicode CLDR, como `US` o `FR`. En la mayoría de los países, estos códigos se corresponden directamente con los códigos ISO-3166-2.
`client_rtt_msec`	Tiempo de transmisión de ida y vuelta estimado entre el balanceador de carga y el cliente HTTP(S), en milisegundos. Es el parámetro de tiempo de ida y vuelta suavizado (SRTT) medido por la pila TCP del balanceador de carga, según el RFC 2988. El RTT suavizado es un algoritmo que gestiona las variaciones y las anomalías que pueden producirse en las mediciones de RTT.
`client_ip_address`	La dirección IP del cliente. Por lo general, se trata de la misma dirección IP del cliente que la penúltima dirección del encabezado `X-Forwarded-For`, a menos que el cliente utilice un proxy o que se haya manipulado el encabezado `X-Forwarded-For`.
`client_port`	Puerto de origen del cliente.
`client_encrypted`	`true` si la conexión entre el cliente y el balanceador de carga está cifrada (con HTTPS, HTTP/2 o HTTP/3); de lo contrario, `false`.
`client_protocol`	El protocolo HTTP que se usa para la comunicación entre el cliente y el balanceador de carga. Uno de los valores `HTTP/1.0`, `HTTP/1.1`, `HTTP/2` o `HTTP/3`.
`origin_request_header`	Refleja el valor del encabezado `Origin` de la solicitud en los casos prácticos de uso compartido de recursos entre dominios (CORS).
`server_ip_address`	La dirección IP del balanceador de carga al que se conecta el cliente. Esto puede ser útil cuando varios balanceadores de carga comparten backends comunes. Es lo mismo que la última dirección IP de la encabezado `X-Forwarded-For`.
`server_port`	Número de puerto de destino al que se conecta el cliente.
`tls_sni_hostname`	Indicación del nombre del servidor (tal como se define en el RFC 6066), si el cliente la proporciona durante el handshake TLS o QUIC. El nombre de host se convierte a minúsculas y se elimina cualquier punto final.
`tls_version`	Versión de TLS negociada entre el cliente y el balanceador de carga durante el handshake de SSL. Entre los valores posibles se incluyen `TLSv1`, `TLSv1.1`, `TLSv1.2` y `TLSv1.3`. Si el cliente se conecta mediante QUIC en lugar de TLS, el valor es `QUIC`.
`tls_cipher_suite`	Conjunto de cifrado negociado durante el handshake TLS. El valor es un número hexadecimal de cuatro dígitos definido por el registro de conjuntos de cifrado TLS de IANA. Por ejemplo, `009C` para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor está vacío en el caso de QUIC y de las conexiones de cliente sin cifrar.
`tls_ja3_fingerprint`	JA3 Huella digital TLS/SSL si el cliente se conecta mediante HTTPS, HTTP/2 o HTTP/3.

El balanceador de carga expande las variables a cadenas vacías cuando no puede determinar sus valores. Por ejemplo:

Parámetros de TLS cuando no se usa TLS
El {origin_request_header} cuando la solicitud no incluye un encabezado Origin
Variables de ubicación geográfica cuando se desconoce la ubicación de la dirección IP

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. Aunque la cabecera X-Forwarded-For original contenga 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 que contienen los paquetes recibidos por el balanceador de carga.

Encabezados personalizados de TLS mutuo

Las siguientes variables de encabezado adicionales están disponibles si se configura TLS mutuo (mTLS) en TargetHttpsProxy del balanceador de carga.

Variable	Descripción
`client_cert_present`	`true` si el cliente ha proporcionado un certificado durante el handshake TLS; de lo contrario, `false`.
`client_cert_chain_verified`	`true` si la cadena de certificados de cliente se verifica con un `TrustStore` configurado; de lo contrario, `false`.
`client_cert_error`	Cadenas predefinidas que representan las condiciones de error. Para obtener más información sobre las cadenas de error, consulta Modos de validación de clientes de mTLS.
`client_cert_sha256_fingerprint`	Huella digital SHA-256 codificada en Base64 del certificado de cliente.
`client_cert_serial_number`	Número de serie del certificado de cliente. Si el número de serie tiene más de 50 bytes, se añade la cadena `client_cert_serial_number_exceeded_size_limit` a `client_cert_error` y el número de serie se establece como una cadena 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 2048 bytes, el ID de SPIFFE se define como una cadena vacía. Si el ID de SPIFFE tiene más de 2048 bytes, se añade la cadena `client_cert_spiffe_id_exceeded_size_limit` a `client_cert_error`.
`client_cert_uri_sans`	Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo URI. Las extensiones SAN se extraen del certificado de cliente. El ID de SPIFFE no se incluye en el campo `client_cert_uri_sans`. Si `client_cert_uri_sans` tiene más de 512 bytes, se añade la cadena `client_cert_uri_sans_exceeded_size_limit` a `client_cert_error` y la lista separada por comas se asigna a una cadena vacía.
`client_cert_dnsname_sans`	Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo DNSName. Las extensiones SAN se extraen del certificado de cliente. Si `client_cert_dnsname_sans` tiene más de 512 bytes, se añade la cadena `client_cert_dnsname_sans_exceeded_size_limit` a `client_cert_error` y la lista separada por comas se asigna a una cadena vacía.
`client_cert_valid_not_before`	Marca de tiempo (cadena de fecha en formato RFC 3339 ) anterior a 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 (cadena de fecha en formato RFC 3339) tras la cual el certificado de cliente no es válido. Por ejemplo, `2022-07-01T18:05:09+00:00`.
`client_cert_issuer_dn`	Campo Issuer completo codificado en Base64 del certificado. Si `client_cert_issuer_dn` tiene más de 512 bytes, se añade la cadena `client_cert_issuer_dn_exceeded_size_limit` a `client_cert_error` y `client_cert_issuer_dn` se define como una cadena vacía.
`client_cert_subject_dn`	Campo Subject completo del certificado codificado en Base64. Si `client_cert_subject_dn` tiene más de 512 bytes, se añade la cadena `client_cert_subject_dn_exceeded_size_limit` a `client_cert_error` y `client_cert_subject_dn` se define como una cadena vacía.
`client_cert_leaf`	El certificado de hoja de cliente de una conexión mTLS establecida en la que el certificado ha superado la validación. La codificación del certificado cumple el estándar RFC 9440: el certificado DER binario se codifica con Base64 (sin saltos de línea, espacios ni otros caracteres que no pertenezcan al alfabeto Base64) y se delimita con dos puntos a cada lado. Si `client_cert_leaf` supera los 16 KB sin codificar, se añade la cadena `client_cert_validated_leaf_exceeded_size_limit` a `client_cert_error` y `client_cert_leaf` se asigna a una cadena vacía.
`client_cert_chain`	Lista de certificados separados por comas, en orden TLS estándar, de la cadena de certificados de cliente de una conexión mTLS establecida en la que el certificado de cliente ha superado la validación, sin incluir el certificado de hoja. La codificación de certificados cumple el estándar RFC 9440. Si el tamaño combinado de `client_cert_leaf` y `client_cert_chain` antes de la codificación Base64 supera los 16 KB, la cadena `client_cert_validated_chain_exceeded_size_limit` se añade a `client_cert_error` y `client_cert_chain` se asigna a una cadena vacía.

Limitaciones

Se aplican las siguientes limitaciones:

No puedes configurar encabezados personalizados en los servicios de backend que usan los balanceadores de carga de aplicaciones externos regionales.

Las siguientes variables de encabezado personalizado no se admiten con los balanceadores de carga de aplicaciones externos regionales:
- cdn_cache_id
- cdn_cache_status
- client_region_subdivision
- client_city
- client_city_lat_long