Como criar cabeçalhos personalizados

Os cabeçalhos personalizados de solicitação e resposta permitem especificar mais cabeçalhos que o balanceador de carga HTTP(S) externo adiciona a solicitações e respostas. Esses cabeçalhos podem incluir informações sobre a conexão do cliente que são detectadas do balanceador de carga, como a latência para o cliente, a localização geográfica do endereço IP do cliente e os 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.

O balanceamento de carga HTTP(S) adiciona determinados cabeçalhos por padrão a todas as solicitações HTTP(S) e respostas que são transmitidas por proxy entre os back-ends e os clientes. Para mais informações, consulte Protocolos de destino.

Antes de começar

  • Se necessário, atualize para a versão mais recente do SDK do Cloud:

    gcloud components update

Como os cabeçalhos personalizados funcionam

Os cabeçalhos personalizados funcionam da seguinte maneira:

  • Quando o balanceador de carga HTTP(S) externo faz uma solicitação ao back-end, o balanceador de carga adiciona cabeçalhos de solicitação.

  • O balanceador de carga HTTP(S) externo define os cabeçalhos de resposta antes de retornar as respostas ao cliente.

Os cabeçalhos de solicitação e resposta não influenciam o comportamento do armazenamento em cache ou do balanceador de carga.

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 têm as seguintes propriedades:

  • 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-IP nem CDN-Loop.
  • O nome do cabeçalho não pode começar com X-Google, X-Goog-, X-GFE ou X-Amz-
  • Um nome de cabeçalho não pode aparecer mais de uma vez na lista de cabeçalhos adicionados.

Os valores do cabeçalho têm as seguintes propriedades:

  • 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.

Por exemplo, é possível especificar um cabeçalho com dois nomes de variáveis, um para a região e outro para a cidade do cliente. A ferramenta de linha de comando gcloud tem uma sinalização para especificar cabeçalhos de solicitação: --custom-request-header. Por exemplo:

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

O formato geral da sinalização é:

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Os valores do cabeçalho precisam ser colocados entre chaves. Por exemplo:

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

Use apenas aspas normais (') neste comando.

Variáveis que podem aparecer no valor do 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.
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 (por exemplo, uma província ou um estado) do país associado ao endereço IP do cliente. 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.
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.

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çalho Origin
  • 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.

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

Como trabalhar com cabeçalhos de solicitação personalizados

Console

Para adicionar cabeçalhos de solicitação personalizados a um serviço de back-end existente:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Em Cabeçalhos de solicitação personalizados, clique em Adicionar cabeçalho.
  7. Insira o nome do cabeçalho e o valor do cabeçalho para o cabeçalho da solicitação personalizada.
  8. Insira qualquer cabeçalho adicional da solicitação personalizada.
  9. Clique em Salvar.

Para remover um cabeçalho de solicitação personalizado de um serviço de back-end:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Clique no X ao lado do nome do cabeçalho da solicitação personalizado que você quer remover.
  7. Clique em Salvar.

gcloud

Para criar um serviço de back-end com cabeçalhos de solicitação personalizados:

gcloud beta 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 beta compute backend-services update BACKEND_SERVICE_NAME \
  --global \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

Observe que o cabeçalho acima substitui todos os cabeçalhos já presentes 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 beta 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"
]

Como trabalhar com cabeçalhos de resposta personalizados

Console

Para adicionar cabeçalhos de solicitação personalizados a um serviço de back-end existente:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Em Cabeçalhos de resposta personalizados, clique em Adicionar cabeçalho.
  7. Insira o nome do cabeçalho e o valor do cabeçalho para o cabeçalho da solicitação personalizada.
  8. Insira qualquer outro cabeçalho de resposta personalizado.
  9. Clique em Salvar.

Para remover um cabeçalho de resposta personalizado de um serviço de back-end:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Clique no X ao lado do nome do cabeçalho de resposta personalizado que você quer remover.
  7. Clique em Salvar.

gcloud

Nos 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.

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

gcloud compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

API

Nos buckets de back-end, use a chamada de API Method: backendBuckets.insert ou Method: backendBuckets.update.

Nos 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 snippet a seguir ao corpo da solicitação JSON:

"cdnPolicy": {
  "customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
}

Como 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.

Limitações

As seguintes limitações se aplicam a cabeçalhos personalizados:

  • Só é possível especificar, no máximo, 16 cabeçalhos de solicitação personalizados por serviço de back-end.
  • Só é possível especificar, no máximo, 16 cabeçalhos de resposta personalizados para cada serviço de back-end.
  • O tamanho total de todos os cabeçalhos de solicitação personalizados por serviço de back-end (nome e valor combinados, antes da expansão da variável) não pode exceder 8 KB.
  • O tamanho total de todos os cabeçalhos de resposta personalizados por serviço de back-end (nome e valor combinados, antes da expansão da variável) não pode exceder 8 KB.

A seguir