Ao configurar extensões usando plug-ins ou frases de destaque para serviços de back-end baseados em ext-proc, é possível especificar os atributos de solicitação e conexão para
encaminhar a esses serviços. Nesta página, descrevemos os atributos compatíveis e especificamos quais deles estão disponíveis para cada tipo de extensão.
Ao configurar extensões para encaminhar atributos específicos, você pode:
- Tomar decisões de roteamento dinâmico.
- Enriqueça os cabeçalhos de solicitação com informações do cliente.
- Implemente políticas de segurança personalizadas com base na localização do cliente ou em parâmetros de TLS.
- Gerar registros personalizados detalhados.
É possível especificar atributos com o campo forwardAttributes na configuração YAML
para extensões de plug-in e de callout. Por exemplo, para extensões de tráfego, consulte Configurar uma extensão de tráfego.
A especificação de atributos com forwardAttributes é compatível com autorização, extensões de borda, rota e tráfego. É possível implementar forwardAttributes usando plug-ins Wasm ou callouts (com o protocolo ext_proc) nos seguintes produtos:
- Balanceadores de carga de aplicativo externos regionais
- Balanceadores de carga de aplicativo internos regionais
- Balanceadores de carga de aplicativos externos globais
- Balanceadores de carga de aplicativo internos entre regiões
A tabela a seguir lista os atributos e as extensões compatíveis:
| Atributo | Descrição | Extensões |
|---|---|---|
request.origin |
O valor do cabeçalho de origem em uma solicitação para casos de uso de compartilhamento de recursos entre origens (CORS). | trânsito |
request.method |
O método de solicitação HTTP, como GET ou
POST. |
autorização, borda, rota, tráfego |
request.mcp_method |
O método de solicitação HTTP, como GET ou
POST. |
autorização |
request.host |
Um equivalente de conveniência a request.headers['host']. |
autorização, borda, rota, tráfego |
request.path |
O caminho do URL HTTP solicitado. | autorização, borda, rota, tráfego |
request.query |
A consulta de URL HTTP, no formato name1=value&name2=value2,
conforme aparece na primeira linha da solicitação HTTP. Nenhuma decodificação é
executada. |
autorização, borda, rota, tráfego |
request.scheme |
O esquema de URL HTTP, como HTTP ou
HTTPS. Os valores deste atributo estão em minúsculas. |
autorização, borda, rota, tráfego |
request.backend_service_name |
O serviço de back-end para onde a solicitação é encaminhada. | autorização, tráfego |
request.backend_service_project_number |
Ao usar a VPC compartilhada, o número do projeto do serviço de back-end para onde a solicitação é encaminhada. | autorização, tráfego |
request.mcp_param |
O parâmetro de MCP. | autorização |
request.user_agent_family |
O tipo de navegador do cliente, derivado dos valores do cabeçalho User-Agent. Esses valores se referem à string de texto bruta que os clientes HTTP
recebidos (como navegadores da Web, apps para dispositivos móveis ou ferramentas automatizadas) enviam
no cabeçalho da solicitação HTTP User-Agent padrão. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais e regionais) |
request.device_request_type |
O tipo de dispositivo do cliente. Os valores possíveis para esse atributo são APPLE, APPLEWEBKIT, BLACKBERRY, DOCOMO, GECKO, GOOGLE, KHTML, KOREAN, MICROSOFT, MSIE, NETFRONT, NOKIA, OBIGO, OPERA, OPENWAVE, OTHER, POLARIS, SEMC, SMIT, TELECA ou USER_DEFINED. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais e regionais) |
response.cdn_cache_id |
O código do local e o ID da instância de cache usada para atender à solicitação. Esse é o mesmo valor preenchido no
campo jsonPayload.cacheId dos registros de solicitação do Cloud CDN.
|
tráfego (somente para balanceadores de carga de aplicativo externos globais) |
response.cdn_cache_status |
O status atual da instância de cache usada para atender à solicitação. Os valores possíveis para esse atributo são hit, miss, revalidated, stale, uncacheable ou disabled. |
tráfego (somente para balanceadores de carga de aplicativo externos globais) |
source.ip |
O endereço IP do cliente. | borda, rota, tráfego |
source.port |
A porta de origem do cliente. | borda, rota, tráfego |
source.client_region |
O país ou a região associada ao endereço IP do cliente.
O valor é um código de região Unicode CLDR, como US
ou FR. Na maioria dos países, esses códigos correspondem diretamente ao padrão ISO-3166-2. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais e regionais) |
source.client_region_subdivision |
A subdivisão (por exemplo, uma província ou um estado) do país associado ao endereço IP do cliente. É 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. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais) |
source.client_city |
O 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: !#$%&'*+-.^_`|~. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais) |
source.client_city_lat_long |
A latitude e a longitude da cidade de origem da solicitação. Por exemplo, 37.386051,-122.083851 para uma solicitação de Mountain View. |
de borda, tráfego (somente para balanceadores de carga de aplicativo externos globais) |
connection.client_encrypted |
O valor é 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, será false. |
trânsito |
connection.client_rtt_msec |
O 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), conforme definido na RFC 2988, que a pilha TCP do balanceador de carga mede. | tráfego (somente para balanceadores de carga de aplicativo externos globais) |
connection.client_protocol |
O protocolo HTTP usado para a comunicação entre o cliente e o balanceador de carga. Pode ser HTTP/1.0,
HTTP/1.1, HTTP/2,
ou HTTP/3. |
trânsito |
connection.server_ip_address |
O endereço IP do balanceador de carga a que o cliente se conecta.
Esse valor pode ser útil quando vários balanceadores de carga compartilham back-ends comuns. É o mesmo que o último endereço IP no cabeçalho
X-Forwarded-For. |
trânsito |
connection.server_port |
O número da porta de destino à qual o cliente se conecta. | trânsito |
connection.sni |
Indicação do nome do servidor (conforme definido na RFC 6066), se fornecida pelo cliente durante o handshake TLS ou QUIC. O nome do host é convertido em letras minúsculas, e qualquer ponto à direita é removido. | autorização, borda, tráfego |
connection.tls_version |
A 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 conectar usando QUIC
em vez de TLS, o valor será QUIC. |
borda, tráfego |
connection.sha256_peer_certificate_digest |
O hash SHA256 codificado em hexadecimal do certificado de mesmo nível na conexão TLS de downstream, se houver. | autorização, borda, tráfego |
connection.tls_cipher_suite |
O 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. Esse valor fica em branco
para QUIC e conexões do cliente não criptografadas. |
trânsito |
connection.tls_ja3_fingerprint |
A impressão digital TLS/SSL JA3 se o cliente se conectar usando
HTTPS, HTTP/2 ou HTTP/3. |
trânsito |
connection.tls_ja4_fingerprint |
A impressão digital TLS/SSL JA4 se o cliente se conectar usando HTTPS,
HTTP/2 ou HTTP/3. |
borda, tráfego |
connection.client_cert_present |
O valor é true se o cliente tiver fornecido um certificado durante o handshake de TLS. Caso contrário, é false. |
autorização, tráfego |
connection.client_cert_chain_verified |
O valor é true se a cadeia de certificados do cliente for verificada em relação a um TrustStore configurado. Caso contrário, será false. |
autorização, tráfego |
connection.client_cert_error |
Strings predefinidas que representam condições de erro. Para mais informações sobre as strings de erro, consulte os modos de validação de cliente mTLS. | autorização, tráfego |
connection.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. |
autorização, tráfego |
connection.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 tiver mais de 2.048 bytes, o client_cert_error será definido como client_cert_spiffe_id_exceeded_size_limit. |
autorização, tráfego |
connection.client_cert_uri_sans |
Uma lista codificada por Base64 separada por vírgulas 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
client_cert_uri_sans. Se client_cert_uri_sans for maior que 512 bytes, client_cert_error será definido como client_cert_uri_sans_exceeded_size_limit e a lista separada por vírgulas será definida como uma string vazia. |
autorização, tráfego |
connection.client_cert_dnsname_sans |
Uma lista codificada por Base64 separada por vírgulas das extensões SAN do tipo DNSName. As extensões do SAN são extraídas do certificado do cliente. Se client_cert_dnsname_sans
for maior que 512 bytes, client_cert_error será
definido como client_cert_dnsname_sans_exceeded_size_limit,
e a lista separada por vírgulas será definida como uma string vazia. |
autorização, tráfego |
connection.client_cert_valid_not_before |
O 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.
|
autorização, tráfego |
connection.client_cert_valid_not_after |
O carimbo de data/hora (no 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.
|
autorização, tráfego |
connection.client_cert_issuer_dn |
A codificação DER codificada em Base64 do campo Issuer
completo do certificado. Se client_cert_issuer_dn
tiver mais de 512 bytes, a string
client_cert_issuer_dn_exceeded_size_limit será adicionada
a client_cert_error, e
client_cert_issuer_dn será definido como uma string vazia. |
autorização, tráfego |
connection.client_cert_subject_dn |
A codificação DER codificada em Base64 do campo Subject
completo do certificado. Se client_cert_subject_dn
tiver mais de 512 bytes, a string
client_cert_subject_dn_exceeded_size_limit será adicionada
a client_cert_error, e
client_cert_subject_dn será definido como uma string vazia. |
autorização, tráfego |
connection.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 está em conformidade com a RFC 9440. Isso significa que o certificado DER binário é codificado em Base64 e delimitado com dois-pontos em ambos os lados. Se client_cert_leaf exceder 16 KB não codificados, a string client_cert_validated_leaf_exceeded_size_limit será adicionada a client_cert_error e client_cert_leaf será definido como uma string vazia. |
autorização, tráfego |
connection.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 está em conformidade
com a 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 será
adicionada a client_cert_error, e
client_cert_chain será definido como uma string vazia. |
autorização, tráfego |
Limitações
Disponibilidade de atributos: nem todos os atributos são compatíveis com todos os tipos de extensão. Para mais informações, consulte a tabela nesta página.
Configuração obrigatória: para enviar atributos à extensão, liste explicitamente os atributos no campo
forwardAttributesda configuração da extensão. Se você não listar um atributo nesse campo, o balanceador de carga não encaminhará esse atributo específico para sua extensão.Limites de tamanho: é possível configurar no máximo 16 atributos para uma única extensão.
Atributos mTLS: os atributos do certificado do cliente (
connection.client_cert_*) são preenchidos nos dados transmitidos para sua extensão somente se você tiver ativado o mTLS e o cliente apresentar um certificado.