Os cabeçalhos de solicitação e resposta personalizados permitem especificar cabeçalhos adicionais que o balanceador de carga pode adicionar a solicitações e respostas HTTP(S). Dependendo das informações detectadas pelo balanceador de carga, esses cabeçalhos podem incluir as seguintes informações:
- Latência para o cliente
- Localização geográfica do endereço IP do cliente
- Parâmetros da conexão TLS
Cabeçalhos de solicitação personalizados são compatíveis com serviços de back-end, enquanto cabeçalhos de resposta personalizados são compatíveis com serviços e buckets de back-end.
Por padrão, o balanceador de carga adiciona determinados cabeçalhos a todas as solicitações e respostas HTTP(S) que ele encaminha por proxy entre back-ends e clientes. Para mais informações, consulte Protocolos de destino.
Antes de começar
Se necessário, atualize para a versão mais recente da CLI do Google Cloud:
gcloud components update
Como os cabeçalhos personalizados funcionam
Os cabeçalhos personalizados funcionam da seguinte maneira:
Quando o balanceador de carga encaminha uma solicitação ao back-end, ele adiciona cabeçalhos de solicitação.
O balanceador de carga adiciona cabeçalhos de solicitação personalizados apenas às solicitações do cliente, não às sondagens de verificação de integridade. Se o back-end exige um cabeçalho específico para autorização que esteja faltando no pacote de verificação de integridade, ele poderá falhar.
O balanceador de carga define os cabeçalhos de resposta antes de retornar as respostas ao cliente.
Para ativar cabeçalhos personalizados, especifique uma lista de cabeçalhos em uma propriedade do serviço ou bucket de back-end.
Especifique cada cabeçalho como uma string header-name:header-value. O cabeçalho precisa conter dois pontos separando o nome e o valor dele.
Os nomes de cabeçalho precisam atender aos seguintes requisitos:
- O nome do cabeçalho precisa ser uma definição válida de nome de campo de cabeçalho HTTP (de acordo com a RFC 7230).
- O nome do cabeçalho não pode ser
X-User-IPnemCDN-Loop. - Os seguintes cabeçalhos salto a salto não podem ser usados:
Keep-Alive,Transfer-Encoding,TE,Connection,Trailer,Upgrade,Proxy-AuthorizationeProxy-Authenticate. De acordo com a RFC 2616 (link em inglês), esses cabeçalhos não são armazenados por caches nem propagados pelos proxies de destino. - O nome do cabeçalho não pode começar com
X-Google,X-Goog-,X-GFEouX-Amz-. - Um nome de cabeçalho não pode aparecer mais de uma vez na lista de cabeçalhos adicionados.
Os valores de cabeçalho precisam atender aos seguintes requisitos:
- O valor do cabeçalho precisa ser uma definição válida de campo de cabeçalho HTTP (segundo a RFC 7230, com formulários obsoletos não permitidos).
- O valor do cabeçalho pode estar em branco.
- O valor do cabeçalho pode incluir uma ou mais variáveis, delimitadas por chaves, que se expandem para valores fornecidos pelo balanceador de carga. Na próxima seção, há uma lista de variáveis permitidas no valor do cabeçalho.
A ferramenta de linha de comando gcloud tem uma flag para especificar
cabeçalhos de solicitação: --custom-request-header. Use este flag para incluir o
nome e o valor do cabeçalho entre aspas simples (').
O formato geral da sinalização é:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
Confira a seguir um exemplo de um valor de cabeçalho com duas variáveis,
client_region e client_city, entre chaves.
--custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'
Para clientes localizados em Mountain View, Califórnia, este seria o cabeçalho adicionado pelo balanceador de carga:
X-Client-Geo-Location:US,Mountain View
Variáveis compatíveis com valores de cabeçalho
As variáveis a seguir podem aparecer em valores de cabeçalho personalizados.
| Variável | Descrição |
|---|---|
| cdn_cache_id | Código do local e ID da instância de cache usada para exibir a solicitação.
Esse é o mesmo valor preenchido no campo jsonPayload.cacheId dos
registros de solicitação do Cloud CDN no Logging.
|
| cdn_cache_status | Status atual do cache. Os valores podem ser hit,
miss, revalidated, stale,
uncacheable ou disabled de qualquer objeto
exibido por um Cloud CDN com back-end ativado.
|
| origin_request_header | Reflete o valor do cabeçalho Origin na solicitação
de casos de uso de compartilhamento de recursos entre origens (CORS).
|
| client_rtt_msec | Tempo estimado de retorno para transmissão entre o balanceador de carga e o cliente HTTP(S), em milissegundos. É o parâmetro de tempo de retorno suavizado (SRTT, na sigla em inglês) medido pela pilha TCP do balanceador de carga, de acordo com a RFC 2988. O RTT suavizado é um algoritmo que lida com variações e anomalias que podem ocorrer em medições de RTT. |
| client_region | O país (ou região) associado ao endereço IP do cliente. Esté
é um código de região Unicode CLDR, como US ou
FR. Na maioria dos países, esses códigos correspondem diretamente
a códigos ISO-3166-2.
|
| client_region_subdivision | Subdivisão do país associado ao endereço IP do cliente, por exemplo, uma província ou um estado. Este é um ID de subdivisão Unicode CLDR, como
USCA ou CAON. Esses códigos Unicode são
derivados das subdivisões definidas pelo padrão ISO-3166-2.
|
| client_city | Nome da cidade de origem da solicitação. Por exemplo,
Mountain View para Mountain View, Califórnia. Não há uma
lista canônica de valores válidos para essa variável. Os nomes das cidades podem
conter letras US-ASCII, números, espaços e os seguintes caracteres:
!#$%&'*+-.^_`|~.
|
| client_city_lat_long | Latitude e longitude da cidade de origem da solicitação.
Por exemplo, 37.386051,-122.083851 para uma solicitação de
Mountain View.
|
| client_ip_address | O endereço IP do cliente. Geralmente, ele é igual ao endereço
IP do cliente que é o penúltimo endereço no
cabeçalho
X-Forwarded-For, a menos que o cliente esteja usando 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 conexão entre o cliente e o balanceador de carga for criptografada (usando HTTPS, HTTP/2 ou HTTP/3); Caso contrário, false.
|
| client_protocol | O protocolo HTTP usado para a comunicação entre o cliente e o balanceador de carga. Um de
HTTP/1.0, HTTP/1.1, HTTP/2,
ou HTTP/3.
|
| server_ip_address | O endereço IP do balanceador de carga a que o cliente se conecta. Isso
pode ser útil quando vários balanceadores de carga compartilham back-ends comuns. Este
é o mesmo que o último endereço IP no
cabeçalho
X-Forwarded-For.
|
| server_port | O número da porta de destino à qual o cliente se conecta. |
| tls_sni_hostname | Indicação do nome do servidor (conforme definido na RFC 6066, em inglês), caso ele seja fornecido pelo cliente durante o handshake do TLS ou do QUIC. O nome do host é convertido para letras minúsculas e qualquer ponto à direita é removido. |
| tls_version | Versão de TLS negociada entre o cliente e o balanceador de carga durante o handshake de SSL. Os valores possíveis incluem TLSv1,
TLSv1.1, TLSv1.2 e TLSv1.3. Se
o cliente se conectar usando QUIC em vez de TLS, o valor será
QUIC.
|
| tls_cipher_suite | Pacote de criptografia negociado durante o handshake de TLS. O valor corresponde a quatro
dígitos hexadecimais definidos pelo
Registro do
pacote de criptografia TLS da IANA.
Por exemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este
valor fica em branco para QUIC e conexões do cliente não criptografadas.
|
| tls_ja3_fingerprint | Impressão digital TLS/SSL JA3 se o cliente se conecta usando HTTPS, HTTP/2 ou HTTP/3. |
O balanceador de carga expande variáveis para strings vazias quando não consegue determinar os valores delas. Por exemplo:
- Variáveis de localização geográfica quando a localização do endereço IP é desconhecida
- Parâmetros TLS quando o TLS não está em uso
- O
{origin_request_header}quando a solicitação não inclui um cabeçalhoOrigin - O cabeçalho
{cdn_cache_status}quando incluído em um cabeçalho de solicitação
Valores geográficos (regiões, subdivisões e cidades) são estimativas baseadas no
endereço IP do cliente. De tempos em tempos, o Google atualiza os dados que fornecem
esses valores para melhorar a precisão e refletir as mudanças geográficas
e políticas. Mesmo que o cabeçalho X-Forwarded-For original contenha informações de local
válidas, o Google estima os locais do cliente usando as informações do endereço IP de origem contidas nos pacotes recebidos pelo balanceador de carga.
Os cabeçalhos adicionados pelo balanceador de carga substituem cabeçalhos já existentes com o mesmo nome. Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas. Quando os nomes de cabeçalho são passados para um back-end HTTP/2, o protocolo HTTP/2 os codifica como minúsculas.
Nos valores de cabeçalho, os espaços em branco iniciais e finais são insignificantes
e não são passados para o back-end. Para permitir chaves nos valores de cabeçalho,
o balanceador de carga interpreta duas chaves de abertura ({{) como
uma única chave de abertura ({) e duas chaves de fechamento (}}) como uma única
chave de fechamento (}).
Cabeçalhos personalizados TLS mútuos
As seguintes variáveis de cabeçalho adicionais estarã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 de TLS. Caso contrário, false.
|
| client_cert_chain_verified | true se a cadeia de certificados do cliente for verificada 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 de 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 do cliente.
Se o número de série for maior que 50 bytes, o client_cert_error será definido como client_cert_serial_number_exceeded_size_limit e o número de série será definido como uma string vazia. |
| client_cert_spiffe_id | O ID do SPIFFE no campo Nome alternativo do assunto (SAN, na sigla em inglês). Se o valor não for válido ou exceder 2.048 bytes, o ID do SPIFFE será definido como uma string vazia. Se o ID SPIFFE for maior que 2.048 bytes, o |
| client_cert_uri_sans | Lista codificada por Base64 separada por vírgula das extensões SAN do tipo URI.
As extensões do SAN são extraídas do certificado do cliente.
O ID do SPIFFE não está incluído no campo Se |
| client_cert_dnsname_sans | Lista codificada por Base64 separada por vírgula das extensões SAN do tipo DNSName. As extensões do SAN são extraídas do certificado do cliente. Se |
| client_cert_valid_not_before | Carimbo de data/hora (formato de string de data RFC 3339) antes do qual o certificado do cliente não é válido.
Por exemplo, 2022-07-01T18:05:09+00:00.
|
| client_cert_valid_not_after | Carimbo de data/hora (formato de string de data RFC 3339) após o qual o certificado do cliente não é válido.
Por exemplo, 2022-07-01T18:05:09+00:00.
|
| client_cert_issuer_dn | Codificação DER codificada em Base64 do campo completo do emissor do certificado. Se o |
| client_cert_subject_dn | Codificação DER codificada em Base64 do campo completo do assunto do certificado. Se o |
| client_cert_leaf | O certificado de folha de cliente para uma conexão mTLS estabelecida em que o certificado passou na validação. A codificação do certificado é compatível com o RFC 9440 (link em inglês). Isso significa que o certificado DER binário é codificado usando Base64 e delimitado com dois-pontos em ambos os lados. Se |
| client_cert_chain | A lista de certificados delimitada por vírgulas, na ordem TLS padrão, da cadeia de certificados do cliente para uma conexão mTLS estabelecida em que o certificado do cliente passou na validação, sem incluir o certificado de folha. A codificação do certificado é compatível com a RFC 9440 (link em inglês). Se o tamanho combinado |
Configurar cabeçalhos de solicitação personalizados
Console
Para adicionar cabeçalhos de solicitação personalizados a um serviço de back-end existente:
- Acesse a página de resumo do balanceamento de carga.
Acessar a página "Balanceamento de carga" - Clique em Back-ends.
- Clique no nome de um serviço de back-end.
- Clique em Editar .
- Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
- Em Cabeçalhos de solicitação personalizados, clique em Adicionar cabeçalho.
- Insira o nome do cabeçalho e o valor do cabeçalho para o cabeçalho da solicitação personalizada.
- Insira qualquer cabeçalho adicional da solicitação personalizada.
- Clique em Salvar.
Para remover um cabeçalho de solicitação personalizado de um serviço de back-end:
- Acesse a página de resumo do balanceamento de carga.
Acessar a página "Balanceamento de carga" - Clique em Back-ends.
- Clique no nome de um serviço de back-end.
- Clique em Editar .
- Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
- Clique no X ao lado do nome do cabeçalho da solicitação personalizado que você quer remover.
- Clique em Salvar.
gcloud
Para especificar cabeçalhos de solicitação personalizados, use o comando gcloud compute backend-services
create
ou gcloud compute backend-services
update
com a sinalização --custom-request-header.
Para criar um serviço de back-end com cabeçalhos de solicitação personalizados:
gcloud 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 adicionar mais cabeçalhos de solicitação, especifique um nome e um valor de cabeçalho
exclusivos repetindo a sinalização --custom-request-header.
Para adicionar cabeçalhos personalizados a um serviço de back-end existente:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
--custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'
A etapa anterior substitui todos os cabeçalhos que já estão no serviço de back-end pelos cabeçalhos de solicitação especificados no comando.
Para remover todos os cabeçalhos de um serviço de back-end:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--no-custom-request-headers
API
Faça uma solicitação PATCH ao método
backendServices.patch:
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME "customRequestHeaders": [ "client_city:Mountain View" ]
Terraform
Para um script do Terraform que cria um balanceador de carga com cabeçalhos personalizados, consulte Exemplos do Terraform para balanceadores de carga de aplicativo externos globais.
Configurar cabeçalhos de resposta personalizados
Console
Para adicionar cabeçalhos de resposta personalizados a um serviço de back-end existente:
- Acesse a página de resumo do balanceamento de carga.
Acessar a página "Balanceamento de carga" - Clique em Back-ends.
- Clique no nome de um serviço de back-end.
- Clique em Editar .
- Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
- Em Cabeçalhos de resposta personalizados, clique em Adicionar cabeçalho.
- Insira o Nome do cabeçalho e o Valor do cabeçalho no cabeçalho de resposta personalizado.
- Insira qualquer outro cabeçalho de resposta personalizado.
- Clique em Salvar.
Para remover um cabeçalho de resposta personalizado de um serviço de back-end:
- Acesse a página de resumo do balanceamento de carga.
Acessar a página "Balanceamento de carga" - Clique em Back-ends.
- Clique no nome de um serviço de back-end.
- Clique em Editar .
- Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
- Clique no X ao lado do nome do cabeçalho de resposta personalizado que você quer remover.
- Clique em Salvar.
gcloud
Para serviços de back-end, use o comando gcloud compute backend-services
create ou gcloud compute backend-services
update com a sinalização --custom-response-header.
Para buckets de back-end, use o comando gcloud compute backend-buckets
create ou gcloud compute backend-buckets
update com a sinalização --custom-response-header.
gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
--custom-response-header='HEADER_NAME:[HEADER_VALUE]'
gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
--custom-response-header='HEADER_NAME:[HEADER_VALUE]'
Exemplo com cabeçalho X-Frame-Options:
gcloud compute backend-buckets update gaming-lab \
--custom-response-header='X-Frame-Options: DENY'
Exemplo com cabeçalho Strict-Transport-Security:
O exemplo a seguir mostra como adicionar um cabeçalho de resposta personalizado para oferecer suporte ao HTTP Strict Transport Security (HSTS):
gcloud compute backend-services update customer-bs-name \
--global \
--custom-response-header='Strict-Transport-Security: max-age=63072000'
API
Para buckets de back-end, use a chamada de API Method: backendBuckets.insert ou Method: backendBuckets.update.
Para serviços de back-end, use a chamada de API Method: backendServices.insert ou Method: backendServices.update.
Use uma das seguintes chamadas de API:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
Adicione o seguinte snippet ao corpo da solicitação JSON:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Terraform
Para um script do Terraform que cria um balanceador de carga com cabeçalhos personalizados, consulte Exemplos do Terraform para balanceadores de carga de aplicativo externos globais.
Definir cabeçalhos de resposta para o Cloud Storage
Se você precisar definir cabeçalhos HTTP em respostas do
Cloud Storage, como política de recursos de origem cruzada,
X-Frame-Options ou cabeçalhos X-XSS-Protection, o Google Cloud oferece
a opção de usar cabeçalhos personalizados do Cloud CDN com o
Cloud Storage. Para isso, configure cabeçalhos personalizados no nível do
bucket de back-end do balanceador de carga, conforme descrito nesta página.
Os cabeçalhos de resposta personalizados configurados no nível do bucket de back-end só são adicionados às respostas se a solicitação do cliente for enviada para o endereço IP do balanceador de carga. Os cabeçalhos personalizados não serão adicionados às respostas se a solicitação do cliente tiver sido feita diretamente para a API Cloud Storage.
Usar cabeçalhos personalizados com o Google Cloud Armor
Ao configurar uma política de segurança no Cloud Armor, você pode inserir um cabeçalho e um valor personalizados. Se a política de segurança do Google Cloud Armor estiver configurada para inserir o mesmo nome de cabeçalho personalizado dos cabeçalhos personalizados do balanceador de carga de aplicativo externo global ou clássico, o valor do cabeçalho especificado no Google Cloud Armor pelo valor preenchido pelo balanceador de carga. Se você não quiser que a política do Google Cloud Armor seja substituída, não use o mesmo nome.
Limitações
As limitações a seguir são válidas para cabeçalhos personalizados usados com balanceadores de carga globais:
- O tamanho total de todos os cabeçalhos de solicitação personalizados (nome e valor combinados, antes da expansão da variável) para cada serviço de back-end não pode exceder 8 KB ou 16 cabeçalhos de solicitação.
- O tamanho total de todos os cabeçalhos de resposta personalizados (nome e valor combinados, antes da expansão da variável) para cada serviço de back-end não pode exceder 8 KB ou 16 cabeçalhos de resposta.
A seguir
- Para um exemplo de caso de uso, consulte Como configurar um balanceador de carga com um back-end externo.