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

Importante: Los balanceadores de cargas de aplicaciones externos globales admiten las transformaciones de encabezados en el mapa de URL y en el servicio de backend. Sin embargo, los balanceadores de cargas de aplicaciones externos regionales y los balanceadores de cargas de aplicaciones internos solo admiten las transformaciones de encabezados en los mapas de URL.

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

Nota: Si usas la consola de Google Cloud para agregar los encabezados de solicitud y respuesta en el mapa de URL, debes ingresar la dirección del host en el campo Hosts y la sección del comparador de rutas del siguiente archivo YAML en el campo Path matcher.

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
    

entre regiones

    gcloud compute url-maps edit URL_MAP_NAME \
        --global
    

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

   defaultService: global/backendServices/BACKEND_SERVICE_1
   name: global-lb-map
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: global/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: global/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 con 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 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, 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