Opções de inicialização do Extensible Service Proxy V2

Registra os valores dos cabeçalhos de solicitação especificados, separados por vírgulas sem espaços. Por exemplo, defina essa sinalização como:

--log_request_headers=foo,bar

Se os valores para o cabeçalho "foo" e "bar" estiverem disponíveis na solicitação, o registro do Endpoints conterá:

request_headers: foo=foo_value;bar=bar_value

Registra os valores dos cabeçalhos de resposta especificados, separados por vírgulas sem espaços. Por exemplo, defina essa sinalização como:

--log_response_headers=baz,bing

Se os valores para o cabeçalho "baz" e "bing" estiverem disponíveis na resposta, o registro do Endpoints conterá:

response_headers: baz=baz_value;bing=bing_value

Registra os valores dos campos primitivos de payload do JWT especificados, separados por vírgulas sem espaços. Por exemplo, defina essa sinalização como:

--log_jwt_payload=sub,project_id,foo.foo_name

Se os valores estiverem disponíveis no payload do JWT, o registro do Endpoints conterá:

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

Os valores no payload do JWT precisam ser campos primitivos (string, número inteiro). Matrizes e objetos JSON não geram registros.

Se especificado, é o caminho para o arquivo local em que entradas de registro de acesso serão gravadas.

Formato de string para especificar o formato do registro de acesso. Se não for definida, a string de formato padrão (em inglês) será usada. Para ver uma descrição detalhada do formato, consulte a referência de strings de formato (em inglês).

Desativa o rastreamento. Por padrão, o rastreamento está ativado.

Quando ativado, o ESPv2 coleta um pequeno número de solicitações para sua API a cada segundo para receber os traces que envia para o Stackdriver Trace. Por padrão, 1 a cada 1.000 solicitações são amostradas. Use a sinalização --tracing_sample_rate para alterar a taxa de amostragem.

O ID do projeto do Google para o rastreamento do Stackdriver.

O rastreamento é um serviço pago. O projeto especificado será cobrado pelo rastreamento.

Por padrão, o ID do projeto do serviço implantado do ESPv2 é cobrado.

O ID do projeto é determinado chamando o servidor de metadados da instância do Google Cloud na inicialização. Se o ESPv2 for implantado fora do Google Cloud (usando o --non_gcp) ), o rastreamento será automaticamente desativado, a menos que ele seja definido explicitamente.

Define a taxa de amostragem de traces como um valor de 0,0 a 1,0. Esse valor especifica a fração de solicitações amostradas.

O valor padrão é 0,001, o que equivale a 1 de 1.000 solicitações.

Essa sinalização especifica quais cabeçalhos HTTP precisam ser verificados para o contexto de trace, com valores de sinalização separados por vírgulas e sem espaços. A ordem é importante: o contexto do trace será derivado do primeiro cabeçalho correspondente.

Os valores possíveis incluem traceparent, x-cloud-trace-context, e grpc-trace-bin.

Se omitidos, os cabeçalhos traceparent e x-cloud-trace-context serão verificados (em ordem).

Consulte Como rastrear a API para mais informações.

Define o cabeçalho de contexto de trace na solicitação enviada ao serviço de back-end.

Essa sinalização especifica o cabeçalho HTTP que deve ser definido, com valores de sinalização separados por vírgulas e sem espaços.

Os valores possíveis incluem traceparent, x-cloud-trace-context, e grpc-trace-bin.

Se omitidos, os cabeçalhos traceparent e x-cloud-trace-context serão enviados.

Consulte Como rastrear a API para mais informações.

Especifica o arquivo JSON da chave da conta de serviço para acessar os serviços do Google. Se a opção for omitida, o proxy entrará em contato com o servidor de metadados do Google Cloud para buscar um token de acesso.

Especifique um caminho para o ESPv2 para carregar a configuração do serviço do endpoint. Com essa sinalização, o ESPv2 vai usar uma estratégia de lançamento "fixa", e as seguintes sinalizações serão ignoradas:

• --service
• --version
• --rollout_strategy

Essa sinalização impedirá que o ESPv2 use a cota da Service Management API.

Os endereços de back-end podem ser especificados usando a sinalização --backend ou o campo backend.rule.address na configuração do serviço. Os usuários da OpenAPI precisam estar cientes de que o campo backend.rule.address é definido pelo campo address na extensão x-google-backend.

A configuração de serviço por operação backend.rule.address geralmente é especificada para roteamento sem servidor. Por padrão, o backend.rule.address terá prioridade sobre a sinalização --backend em cada operação individual.

Ative essa sinalização se quiser que a sinalização --backend tenha prioridade. Isso é útil no desenvolvimento em estações de trabalho locais. É possível usar a mesma configuração de serviço de produção, mas substitua o endereço de back-end usando a sinalização --backend para testes locais.

Observação: somente o endereço será substituído. Todos os outros componentes de backend.rule ainda serão aplicados (prazos, autenticação de back-end, tradução de caminho etc.).

Para ver informações detalhadas sobre a configuração de HttpConnectionManager, consulte referência do Envoy (em inglês). O padrão é off.

A expressão regular no exemplo anterior permite uma origem com http ou https e qualquer subdomínio de example.com.

Quando você define essa opção em um arquivo de configuração do Kubernetes, é preciso adicionar um caractere de barra invertida extra para escapar ambas as instâncias de \ na string. Por exemplo:

Quando definir essa opção no script gcloud_build_image para o Cloud Run, tente evitar o uso de caracteres com escape e barras invertidas, eles podem não ser transmitidos corretamente do script bash para o proxy na inicialização. Em vez de sequências meta, use classes de caracteres. Por exemplo: Original: \d Recommended: [0-9]

Define o tempo limite em segundos das solicitações feitas para serviços externos, exceto para o back-end e para o Google Service Control. Ele inclui o Google ServiceManagement, o servidor de metadados e o servidor do Google IAM. Precisa ser > 0, e o padrão será de 30 segundos se não estiver definido.

Em caso de falhas na rede ao se conectar ao controle de serviço do Google, as solicitações serão permitidas se essa sinalização estiver ativada. O padrão é on.

As condições em que o ESPv2 realiza novas tentativas nos back-ends. Uma ou mais condições retryOn podem ser especificadas usando uma lista separada por vírgulas. O padrão é reset,connect-failure,refused-stream. Para desativar a nova tentativa, defina essa sinalização como vazia.

Consulte os links abaixo para ver as condições aceitas:

• x-envoy-retry-on
• x-envoy-retry-grpc-on

Especifica se os campos primitivos serão impressos para a transcodificação grpc-json. Por padrão, os campos primitivos com valores padrão serão omitidos na saída JSON. Por exemplo, um campo int32 definido como 0 será omitido. Se você definir essa sinalização como true, o comportamento padrão será substituído e os campos primitivos serão impressos, independentemente dos valores. O padrão é false.

Especifica se os enums serão impressos como ints para a transcodificação grpc-json. Por padrão, eles são renderizados como strings. O padrão é false.

Se verdadeiro, use o delimitador de nova linha para separar as mensagens de streaming de resposta. Se for falso, todas as mensagens de streaming de resposta serão transcodificadas em uma matriz JSON.

Normalmente, os valores de tipo enumerado proto precisam estar em letras maiúsculas quando usados em JSON. Defina essa flag como "true" se a solicitação JSON usar valores de tipo enumerado sem letras maiúsculas.

Especifica se os nomes de campo proto serão preservados na transcodificação grpc-json. Por padrão, o protobuf gera nomes de campo JSON usando a opção json_name ou, em letras minúsculas na primeira palavra, nessa ordem. Definir essa sinalização manterá os nomes de campo originais. O padrão é false.

Uma lista de parâmetros de consulta separados por vírgulas a serem ignorados no mapeamento do método de transcodificação na transcodificação grpc-json. Por padrão, o filtro do transcodificador não transcodifica uma solicitação com parâmetros de consulta desconhecidos/inválidos.

Especifica se os parâmetros de consulta que não podem ser mapeados para um campo protobuf correspondente na transcodificação grpc-json serão ignorados. Use isso se não for possível controlar os parâmetros de consulta nem conhecê-los antecipadamente. Caso contrário, use --transcoding_ignore_query_parameters. O padrão é false.

Por padrão, os sinais de adição "+" nos parâmetros de consulta não têm escape para o espaço " " na transcodificação datalab-json. Ele é compatível com HTML 2.0. Se não for o caso, defina essa sinalização como verdadeira para desativar esse recurso.

Adicione um cabeçalho HTTP à solicitação antes de enviá-lo ao back-end upstream. Se o cabeçalho já estiver na solicitação, o valor dele será substituído pelo novo.

Ele é compatível com as variáveis personalizadas do Envoy.

Esse argumento pode ser repetido várias vezes para especificar vários cabeçalhos. Por exemplo:
--add_request_header=key1=value1
--add_request_header=key2=value2.

Anexe um cabeçalho HTTP à solicitação antes do envio ao back-end upstream. Se o cabeçalho já estiver na solicitação, o novo valor será anexado.

Ele é compatível com as variáveis personalizadas do Envoy.

Esse argumento pode ser repetido várias vezes para especificar vários cabeçalhos. Por exemplo:
--append_request_header=key1=value1
--append_request_header=key2=value2.

Adicione um cabeçalho HTTP à resposta antes de enviá-la ao cliente downstream. Se o cabeçalho já estiver na resposta, ele será substituído pelo novo.

Ele é compatível com as variáveis personalizadas do Envoy.

Esse argumento pode ser repetido várias vezes para especificar vários cabeçalhos. Por exemplo:
--add_response_header=key1=value1
--add_response_header=key2=value2.

Anexe um cabeçalho HTTP à resposta antes de enviá-la ao cliente downstream. Se o cabeçalho já estiver na resposta, o novo será anexado.

Ele é compatível com as variáveis personalizadas do Envoy.

Esse argumento pode ser repetido várias vezes para especificar vários cabeçalhos. Por exemplo:
--append_response_header=key1=value1
--append_response_header=key2=value2.

Permite que nomes de cabeçalho com sublinhado sejam transmitidos. O padrão é false.

O caractere sublinhado é permitido em nomes de cabeçalho pelo RFC-7230. No entanto, esse comportamento é implementado como uma medida de segurança, porque alguns sistemas tratam _ e - como intercambiáveis.

Configurar a quantidade máxima de dados armazenados em buffer para cada corpo da solicitação/resposta, em bytes. Quando não definido, o padrão é decidido pelo Envoy. Consulte a configuração do listener do Envoy.

Desative a normalização do cabeçalho HTTP path de acordo com a RFC 3986. Recomendamos manter esta opção ativada se o back-end executar a normalização de caminho por padrão.

A tabela a seguir fornece exemplos da solicitação path que o back-end vai receber do ESPv2 com base na configuração dessa sinalização.

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------
     

Por padrão, o ESPv2 normaliza os caminhos. Desative o recurso somente se o tráfego for afetado pelo comportamento.

Observação: de acordo com a RFC 3986, essa opção não tem escape para caracteres de barra codificados por porcentagem. Consulte a sinalização --disallow_escaped_slashes_in_path para ativar esse comportamento incompatível.

Observação: não será possível fazer a normalização de caso da RFC 3986, mesmo que a opção esteja ativada.

Para mais detalhes, consulte Noções básicas sobre modelos de caminho.

Desativa a mesclagem de barras adjacentes no cabeçalho HTTP path. Recomendamos manter esta opção ativada se o back-end funcionar com a mesclagem por padrão.

A tabela a seguir fornece exemplos da solicitação path que o back-end vai receber do ESPv2 com base na configuração dessa sinalização.

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------
     

Por padrão, o ESPv2 mescla barras. Desative o recurso somente se o tráfego for afetado pelo comportamento.

Para mais detalhes, consulte Noções básicas sobre modelos de caminho.

Não permite solicitações com caracteres de barra de escape codificados por porcentagem:

• %2F ou %2f é tratado como uma /
• %5C ou %5c é tratado como uma \

Quando ativado, o comportamento depende do protocolo usado:

• Para back-ends da OpenAPI, os caminhos de solicitação com barras de escape codificadas por porcentagem se tornarão automaticamente sem escape com o redirecionamento.
• Para back-ends de gRPC, os caminhos de solicitação com barras de escape codificadas por porcentagem serão rejeitados (o gRPC não é compatível com redirecionamentos).

Essa opção não está em conformidade com a RFC 3986, então fica desativada por padrão. Se o back-end não estiver de acordo com a RFC 3986 e tiver barras de escape, será necessário ativar essa opção no ESPv2. Isso evita ataques de confusão de caminhos que resultem na aplicação dos requisitos de segurança.

Para mais detalhes, consulte Noções básicas sobre modelos de caminho.

Especifique o número de novas tentativas na política de repetição de busca do JWKS remoto. O padrão é 0, sem nova tentativa.

Especifique o intervalo de base da retirada exponencial da repetição de busca do JWKS em milissegundos. O padrão será 200ms, se não for definido.

Especifique o intervalo máximo de retirada exponencial da repetição de busca do JWKS em milissegundos. Se não for definido, o padrão será 32s.

Especifique a duração do cache de chave pública JWT em segundos. O padrão será 5 minutos, se não for definido.

Aplicar apenas quando a sinalização --disable_jwks_async_fetch não estiver definida. Esta sinalização determina se o ESPv2 aguardará a busca inicial jwks. concluir antes de vincular a porta do listener. Se for falso, ele aguardará. O padrão é "false".

Especifique o número de tokens JWT exclusivos como o tamanho máximo de cache do JWT. O cache armazena apenas tokens verificados. Se for 0, o cache JWT será desativado. Essa sinalização limita o uso da memória para o cache do JWT. A memória usada pelo cache é aproximadamente (tamanho do token + 64 bytes) por token. Se não for especificado, o padrão será 100.000.

Normalmente, o campo aud do JWT é verificado em relação aos públicos-alvo especificados no campo x-google-audiences da OpenAPI. Essa flag muda o comportamento quando o campo x-google-audiences não é especificado. Quando o campo x-google-audiences não é especificado e essa flag não é usada, o nome do serviço é usado para verificar o campo aud do JWT. Se essa sinalização for usada, o campo aud do JWT não será verificado.