Crie cabeçalhos personalizados em mapas de URLs

Esta página descreve como os cabeçalhos personalizados funcionam nos mapas de URLs usados por equilibradores de carga de aplicações internos regionais e equilibradores de carga de aplicações internos entre regiões.

Os cabeçalhos de pedidos e respostas personalizados permitem-lhe especificar cabeçalhos adicionais que o balanceador de carga pode adicionar a pedidos e respostas HTTP(S). Consoante as informações que o equilibrador de carga deteta, estes cabeçalhos podem incluir as seguintes informações:

• Latência para o cliente

• Parâmetros da ligação TLS

Importante: os equilibradores de carga de aplicações externos globais suportam transformações de cabeçalhos no mapa de URLs e no serviço de back-end. No entanto, os balanceadores de carga de aplicações internos regionais e os balanceadores de carga de aplicações internos entre regiões só suportam transformações de cabeçalhos em mapas de URLs.

Antes de começar

Se necessário, atualize para a versão mais recente da CLI Google Cloud:

gcloud components update

Como funcionam os cabeçalhos personalizados

Os cabeçalhos personalizados funcionam da seguinte forma:

• Quando o balanceador de carga faz um pedido ao back-end, o balanceador de carga adiciona cabeçalhos de pedidos.

  O equilibrador de carga adiciona cabeçalhos de pedidos personalizados apenas aos pedidos do cliente e não às sondagens de verificação do estado. Se o seu back-end exigir um cabeçalho específico para autorização que esteja em falta no pacote de verificação de funcionamento, a verificação de funcionamento pode falhar.

• O balanceador de carga define os cabeçalhos de resposta antes de devolver uma resposta ao cliente.

Para ativar cabeçalhos personalizados para equilibradores de carga de aplicações internos regionais e equilibradores de carga de aplicações internos entre regiões, especifique uma lista de nomes de cabeçalhos e valores de cabeçalhos no ficheiro de configuração do mapa de URLs.

Os nomes dos cabeçalhos têm de ter as seguintes propriedades:

• O nome do cabeçalho tem de ser uma definição de nome de campo de cabeçalho HTTP válida de acordo com o RFC 7230.
• O nome do cabeçalho não pode ser X-User-IP.
• O nome do cabeçalho não pode começar por X-Google, X-Goog-, X-GFE, ou X-Amz-.
• Os seguintes cabeçalhos hop-by-hop não podem ser usados: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer e Upgrade. De acordo com a RFC 2616, estes cabeçalhos não são armazenados em cache nem propagados pelos proxies de destino.
• O nome do cabeçalho não pode ser Host nem authority. Host e authority são palavras-chave especiais reservadas pela Google Cloud. Não pode modificar estes cabeçalhos para equilibradores de carga baseados no Envoy. Em alternativa, recomendamos que crie outros cabeçalhos personalizados (por exemplo, MyHost) para não interferir com os nomes de cabeçalhos reservados.
• Um nome de cabeçalho não pode aparecer mais do que uma vez na lista de cabeçalhos.

Os nomes dos cabeçalhos não são sensíveis a maiúsculas e minúsculas. Quando os nomes dos cabeçalhos são transmitidos a um back-end HTTP/2, o protocolo HTTP/2 codifica os nomes dos cabeçalhos em letras minúsculas.

Os valores dos cabeçalhos têm de ter as seguintes propriedades:

• O valor do cabeçalho tem de ser uma definição de campo de cabeçalho HTTP válida de acordo com a RFC 7230, com formulários obsoletos não permitidos.
• O valor do cabeçalho não pode estar em branco. Os cabeçalhos em branco são rejeitados.
• O valor do cabeçalho pode incluir uma ou mais variáveis, entre chavetas, que se expandem para valores fornecidos pelo equilibrador de carga. Para ver uma lista completa das variáveis permitidas no valor do cabeçalho, consulte o artigo Variáveis que podem aparecer no valor do cabeçalho.

Nos valores dos cabeçalhos, os espaços em branco à esquerda e à direita são insignificantes e não são transmitidos ao back-end. Para permitir chavetas nos valores dos cabeçalhos, o equilibrador de carga interpreta duas chavetas de abertura ({{) como uma única chaveta de abertura ({) e duas chavetas de fecho (}}) como uma única chaveta de fecho (}).

Adicione cabeçalhos de pedidos ou respostas

Para adicionar cabeçalhos de pedidos ou respostas, use a CLI gcloud para editar o mapa de URLs da seguinte forma:

Nota: se estiver a usar a Google Cloud consola para adicionar os cabeçalhos de pedido e resposta no mapa de URLs, tem de introduzir o endereço do anfitrião no campo Anfitriões e a secção de correspondência de caminhos do seguinte YAML no campo Correspondência de caminhos.

Regional

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

Segue-se um exemplo de um ficheiro YAML que mostra como usar variáveis em cabeçalhos 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
    

Entre regiões

    gcloud compute url-maps edit URL_MAP_NAME \
        --global
    

Segue-se um exemplo de um ficheiro YAML que mostra como usar variáveis em cabeçalhos 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
    

Tenha em atenção os seguintes comportamentos:

• Se um cabeçalho de resposta com variáveis personalizadas for resolvido como uma string vazia, é removido.
• Se um cabeçalho de pedido com variáveis personalizadas for resolvido como uma string vazia, é mantido com um marcador de posição de string vazia.
• Se um cabeçalho do pedido personalizado incluir uma variável personalizada e um pedido de cliente recebido também incluir o mesmo cabeçalho, o valor do cabeçalho do pedido do cliente é substituído pelo novo valor fornecido pelo cabeçalho personalizado do equilibrador de carga.

Variáveis que podem aparecer no valor do cabeçalho

As seguintes variáveis podem aparecer em valores de cabeçalho personalizados.

Variável	Descrição
client_rtt_msec	Tempo de transmissão de ida e volta estimado entre o balanceador de carga e o cliente HTTP(S), em milissegundos. Este é o parâmetro de tempo de ida e volta suavizado (SRTT) medido pela pilha TCP do balanceador de carga, por RFC 2988. O RTT suavizado é um algoritmo que lida com variações e anomalias que podem ocorrer nas medições de RTT.
client_ip_address	O endereço IP do cliente. Normalmente, é o mesmo que o endereço IP do cliente, que é o penúltimo endereço no cabeçalho X-Forwarded-For, a menos que o cliente esteja a usar um proxy ou o cabeçalho X-Forwarded-For tenha sido adulterado.
client_port	A porta de origem do cliente.
client_encrypted	true se a ligação entre o cliente e o balanceador de carga estiver encriptada (através de HTTPS, HTTP/2 ou HTTP/3); caso contrário, false.
client_protocol	O protocolo HTTP usado para comunicação entre o cliente e o balanceador de carga. Uma das seguintes opções: HTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3.
origin_request_header	Reflete o valor do cabeçalho Origin no pedido para exemplos de utilização da partilha de recursos de origem cruzada (CORS).
server_ip_address	O endereço IP do balanceador de carga ao qual o cliente se liga. Isto pode ser útil quando vários equilibradores de carga partilham back-ends comuns. Isto é o mesmo que o último endereço IP no cabeçalho X-Forwarded-For.
server_port	O número da porta de destino ao qual o cliente se liga.
tls_sni_hostname	Indicação do nome do servidor (conforme definido na RFC 6066), se fornecida pelo cliente durante o handshake do TLS ou QUIC. O nome de anfitrião é convertido em minúsculas e todos os pontos finais são removidos.
tls_version	Versão do TLS negociada entre o cliente e o balanceador de carga durante o handshake SSL. Os valores possíveis incluem: TLSv1, TLSv1.1, TLSv1.2 e TLSv1.3. Se o cliente se ligar através do QUIC em vez do TLS, o valor é QUIC.
tls_cipher_suite	Conjunto de cifras negociado durante o handshake TLS. O valor é composto por quatro dígitos hexadecimais definidos pelo IANA TLS Cipher Suite Registry, por exemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor está vazio para QUIC e para ligações de clientes não encriptadas.
tls_ja3_fingerprint	JA3 Impressão digital TLS/SSL se o cliente se ligar através de HTTPS, HTTP/2 ou HTTP/3.

O balanceador de carga expande as variáveis para strings vazias quando não consegue determinar os respetivos valores. Por exemplo:

• Parâmetros TLS quando o TLS não está em utilização

• O {origin_request_header} quando o pedido não inclui um cabeçalho Origin

Os valores geográficos são estimativas baseadas no endereço IP do cliente. Periodicamente, a Google atualiza os dados que fornecem estes valores para melhorar a precisão e refletir as alterações geográficas e políticas. Mesmo que o cabeçalho X-Forwarded-For original contenha informações de localização válidas, a Google estima as localizações dos clientes através das informações do endereço IP de origem contidas nos pacotes recebidos pelo equilibrador de carga.

Cabeçalhos personalizados do TLS mútuo

As seguintes variáveis de cabeçalho adicionais estão disponíveis se o TLS mútuo (mTLS) estiver configurado no TargetHttpsProxy do balanceador de carga.

Variável	Descrição
client_cert_present	true se o cliente tiver fornecido um certificado durante o handshake TLS; caso contrário, false.
client_cert_chain_verified	true se a cadeia de certificados de cliente for validada em relação a um TrustStore configurado; caso contrário, false.
client_cert_error	Strings predefinidas que representam as condições de erro. Para mais informações sobre as strings de erro, consulte os modos de validação do cliente mTLS.
client_cert_sha256_fingerprint	Impressão digital SHA-256 codificada em Base64 do certificado do cliente.
client_cert_serial_number	O número de série do certificado de cliente. Se o número de série tiver mais de 50 bytes, a string client_cert_serial_number_exceeded_size_limit é adicionada a client_cert_error e o número de série é definido como uma string vazia.
client_cert_spiffe_id	O ID SPIFFE do campo de nome alternativo de assunto (SAN). Se o valor não for válido ou exceder 2048 bytes, o ID SPIFFE é definido como uma string vazia. Se o SPIFFE ID tiver mais de 2048 bytes, a string client_cert_spiffe_id_exceeded_size_limit é adicionada a client_cert_error.
client_cert_uri_sans	Lista separada por vírgulas codificada em Base64 das extensões SAN do tipo URI. As extensões SAN são extraídas do certificado de cliente. O SPIFFE ID não está incluído no campo client_cert_uri_sans. Se o client_cert_uri_sans tiver mais de 512 bytes, a string client_cert_uri_sans_exceeded_size_limit é adicionada a client_cert_error e a lista separada por vírgulas é definida como uma string vazia.
client_cert_dnsname_sans	Lista codificada em Base64 separada por vírgulas das extensões SAN do tipo DNSName. As extensões SAN são extraídas do certificado de cliente. Se o client_cert_dnsname_sans tiver mais de 512 bytes, a string client_cert_dnsname_sans_exceeded_size_limit é adicionada a client_cert_error e a lista separada por vírgulas é definida como uma string vazia.
client_cert_valid_not_before	Data/hora (RFC 3339 formato de string de data) antes da qual o certificado de cliente não é válido. Por exemplo, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after	Data/hora (RFC 3339 formato de string de data) após a qual o certificado de cliente não é válido. Por exemplo, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn	Campo Emissor completo codificado em Base64 do certificado. Se client_cert_issuer_dn tiver mais de 512 bytes, a string client_cert_issuer_dn_exceeded_size_limit é adicionada a client_cert_error e client_cert_issuer_dn é definida como uma string vazia.
client_cert_subject_dn	Campo Subject completo codificado em Base64 do certificado. Se o client_cert_subject_dn tiver mais de 512 bytes, a string client_cert_subject_dn_exceeded_size_limit é adicionada a client_cert_error e client_cert_subject_dn é definida como uma string vazia.
client_cert_leaf	O certificado de folha do cliente para uma ligação mTLS estabelecida em que o certificado passou na validação. A codificação do certificado está em conformidade com a RFC 9440: o certificado DER binário é codificado com Base64 (sem quebras de linha, espaços ou outros carateres fora do alfabeto Base64) e delimitado com dois pontos de cada lado. Se client_cert_leaf exceder 16 KB sem codificação, a string client_cert_validated_leaf_exceeded_size_limit é adicionada a client_cert_error e client_cert_leaf é definida como uma string vazia.
client_cert_chain	A lista de certificados delimitada por vírgulas, na ordem TLS padrão, da cadeia de certificados de cliente para uma ligação mTLS estabelecida em que o certificado de cliente passou na validação, não incluindo o certificado principal. A codificação de certificados está em conformidade com a norma RFC 9440. Se o tamanho combinado de client_cert_leaf e client_cert_chain antes da codificação Base64 exceder 16 KB, a string client_cert_validated_chain_exceeded_size_limit é adicionada a client_cert_error e client_cert_chain é definida como uma string vazia.

Limitações

Aplicam-se as seguintes limitações:

• Não pode configurar cabeçalhos personalizados em serviços de back-end usados por Application Load Balancers internos regionais e Application Load Balancers internos entre regiões.