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. Esta página descreve os atributos compatíveis e especifica quais estão disponíveis para cada tipo de extensão.
Ao configurar extensões para encaminhar atributos específicos, você pode:
- Tome decisões de roteamento dinâmicas.
- 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 extensões de autorização, de borda, de rota e de 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áfego |
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 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) |
request.header_order |
A ordem dos cabeçalhos HTTP na solicitação do cliente como uma
string separada por vírgulas de nomes de cabeçalho. Por exemplo,
host,accept,cookie. Esse atributo aceita os seguintes cabeçalhos:
accept, accept-charset,
accept-encoding, accept-language,
connection, content-length,
content-type, cookie, host,
if-modified-since, ping-from,
ping-to, pragma, referer,
user-agent, via e
x-forwarded-for. |
tráfego (somente para balanceadores de carga de aplicativo externos globais) |
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ções 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 regional CLDR Unicode, como US
ou FR. Na maioria dos países, esses códigos correspondem diretamente aos códigos 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. 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. |
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áfego |
connection.client_rtt_msec |
O tempo estimado de retorno para transmissão entre o balanceador de carga e o cliente HTTP(S), em milissegundos. Esse é o parâmetro de tempo de retorno suavizado (SRTT), 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áfego |
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áfego |
connection.server_port |
O número da porta de destino à qual o cliente se conecta. | tráfego |
connection.sni |
Indicação do nome do servidor (conforme definido na RFC 6066), 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. | 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 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. |
borda, tráfego |
connection.sha256_peer_certificate_digest |
O hash SHA256 com codificação 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 é composto por quatro dígitos hexadecimais definidos pelo registro de pacotes 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áfego |
connection.tls_ja3_fingerprint |
A impressão digital TLS/SSL JA3 se o cliente se conectar usando
HTTPS, HTTP/2 ou HTTP/3. |
tráfego |
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 forneceu 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 separada por vírgulas e codificada em Base64 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 separada por vírgulas e codificada em Base64 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 vai 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 à sua extensão somente se você tiver ativado a mTLS e o cliente apresentar um certificado.