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

OpenAPI | gRPC

O Extensible Service Proxy V2 (ESPv2) é um proxy baseado em Envoy que permite que o Cloud Endpoints forneça recursos de gerenciamento de APIs. Para configurar o ESPv2, especifique as sinalizações de configuração ao implantar o serviço do ESPv2.

Como definir sinalizações de configuração

O método para definir sinalizações de configuração do ESPv2 varia de acordo com a plataforma de implantação, conforme é descrito nas seções a seguir.

VM do Compute Engine

As sinalizações de configuração do ESPv2 para o Compute Engine são especificadas no comando docker run. Por exemplo:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Neste exemplo, --service, --rollout_strategy e --backend são as sinalizações de configuração do ESPv2.

GKE e Kubernetes

É possível especificar sinalizações de configuração do GKE e do Kubernetes no campo args do arquivo de manifesto de implantação. Por exemplo:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

Neste exemplo, --listener_port, --backend, --service e --rollout_strategy são as sinalizações de configuração do ESPv2.

Cloud Run para plataformas sem servidor

Para especificar opções de inicialização do Cloud Run sem servidor, use a variável de ambiente ESPv2_ARGS. A variável pode ser configurada no comando gcloud run deploy usando a opção --set-env-vars.

Por exemplo:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

Neste exemplo, --enable_debug é a sinalização de configuração do ESPv2.

Consulte Cloud Functions para OpenAPI, Cloud Run para OpenAPI ou Cloud Run para gRPC para mais informações sobre o comando gcloud run deploy.

Para definir vários argumentos na variável de ambiente ESPv2_ARGS, especifique um delimitador personalizado e use-o para separar vários argumentos. Não use vírgula como delimitador. Coloque o delimitador personalizado no início da variável de ambiente ESPv2_ARGS, cercado por acentos circunflexos.

O exemplo a seguir usa ++ como delimitador:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

Se a sinalização que você está configurando contiver vírgulas, será necessário definir a variável de ambiente ESPv2_ARGS no script gcloud_build_image (em inglês).

Por exemplo, para adicionar a sinalização --cors_allow_methods=PUT,POST,GET:

• Faça o download do script gcloud_build_image.
• Edite gcloud_build_image como mostrado abaixo:

  cat <<EOF > Dockerfile
    FROM BASE_IMAGE
  
    ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
    COPY service.json \ENDPOINTS_SERVICE_PATH
  
    ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
  
    ENTRYPOINT ["/env_start_proxy.py"]
    EOF

  Observação: um delimitador personalizado é usado para separar vários argumentos.
• Execute o script gcloud_build_image para criar a imagem.

Sinalizações de configuração do ESPv2

As sinalizações de configuração do ESPv2 podem ser agrupadas nas seguintes categorias:

• Configuração sem servidor
• Logging
• Rastreamento
• Verificação de integridade
• Como depurar
• Teste local
• Implementação fora do Google Cloud
• Extração de IP do cliente
• Suporte ao CORS
• Suporte TLS
• Tempo limite e novas tentativas
• Transcodificação do gRPC
• Modificação de solicitação e resposta
• Opções de segurança
• Autenticação JWT

Outros exemplos genéricos e texto de ajuda de sinalizações do ESPv2 podem ser encontrados no repositório do GitHub.

Configuração sem servidor

Essas sinalizações são necessárias para executar o ESPv2 em plataformas sem servidor, como o GKE, o Compute Engine e o Kubernetes. Elas não podem ser definidas quando implantadas no Cloud Run para plataformas sem servidor.

Observação: para usuários do Kubernetes, NÃO coloque os valores dos campos entre aspas nos arquivos de configuração. Por exemplo, --cors_allow_origin="http://example.com" vai atribuir o valor de string \"http://example.com\" ao campo cor_allow_origin em vez do valor de string pretendido http://example.com.

``

Sinalização	Descrição
--service	Define o nome do serviço do Endpoints.
--version	Define o ID de configuração do serviço do Endpoints.
--rollout_strategy	Especifica a estratégia de lançamento da configuração do serviço, [fixed|managed]. O padrão é fixed.
--listener_port	Identifica a porta para aceitar conexões downstream. É compatível com conexões HTTP/1.x, HTTP/2 e gRPC. O padrão é 8080.
--backend	Especifica o endereço do servidor de aplicativos de back-end local. Os esquemas válidos são http, https, grpc e grpcs, se incluídos. O esquema padrão é >http.

Logging

Use essas sinalizações para configurar o ESPv2 para gravar informações adicionais no registro do Stackdriver.

Bandeira	Descrição
--log_request_headers	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
--log_response_headers	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
--log_jwt_payloads	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.
--access_log	Se especificado, é o caminho para o arquivo local em que entradas de registro de acesso serão gravadas.
--access_log_format	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).

Rastreamento

Use estas sinalizações para configurar os dados de rastreamento do ESPv2 enviados para o Stackdriver. Esses sinalizadores só são válidos quando o rastreamento está ativado.

Bandeira	Descrição
--disable_tracing	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.
--tracing_project_id	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 a flag --non_gcp), o rastreamento será desativado automaticamente, a menos que essa flag seja definida explicitamente.
--tracing_sample_rate	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.
--tracing_incoming_context	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.
--tracing_outgoing_context	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.

Verificação de integridade

Use estas sinalizações para configurar as verificações de integridade do ESPv2. A primeira sinalização pode ser usada para configurar um gerenciador de integridade para responder às chamadas de verificação de integridade. As outras sinalizações podem ser usadas para ativar a verificação de integridade do back-end do gRPC.

/tbody>

Bandeira	Descrição
-z, --healthz	Defina um endpoint de verificação de integridade. Por exemplo, -z healthz faz o ESPv2 retornar o código 200 para o caminho /healthz.
--health_check_grpc_backend	Ative o ESPv2 para verificar periodicamente o serviço de integridade do gRPC em busca de um back-end especificado pela sinalização --backend. O back-end precisa usar o protocolo gRPC e implementar o protocolo de verificação de integridade do gRPC (em inglês). O endpoint de verificação de integridade ativado pela sinalização --healthz refletirá o resultado da verificação de integridade do back-end.
--health_check_grpc_backend_service	Especifique o nome do serviço ao chamar o protocolo de verificação de integridade gRPC de back-end. O valor dessa sinalização só é aplicado quando a sinalização --health_check_grpc_backend é usada. Ela é opcional e, se não for definida, o padrão será vazio. Um nome de serviço vazio é consultar o status geral de integridade do servidor gRPC.
--health_check_grpc_backend_interval	Especifique o intervalo de verificação e o tempo limite da solicitação ao chamar o serviço gRPC de back-end. O valor dessa sinalização só é aplicado quando a sinalização --health_check_grpc_backend é usada. O padrão é 1 segundo. O formato aceito é uma sequência de números decimais, cada um com uma fração opcional e um sufixo de unidade, como "5s", "100ms" ou "2m". As unidades de tempo válidas são "m" para minutos, "s" para segundos e "ms" para milissegundos.

Como depurar

Use estas sinalizações para configurar a depuração do ESPv2. Essas sinalizações podem ser usadas para configurar uma porta de administrador do Envoy para buscar configuração e estatísticas ou executar o Envoy no modo de depuração para gravar informações de nível de depuração no registro.

Bandeira	Descrição
--status_port, --admin_port	Ative o administrador do ESPv2 no Envoy nessa porta. Consulte a referência da interface de administração do Envoy (em inglês) para mais detalhes. A porta de administrador fica desativada por padrão.
--enable_debug	Ative os registros de nível de depuração e adicione cabeçalhos de depuração.

Implantação fora do Google Cloud

Se o ESPv2 for implantado em um ambiente que não seja do Google Cloud, as flags a seguir poderão ser necessárias.

Sinalização	Descrição
--service_account_key	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.
--dns_resolver_addresses	Os endereços dos resolvedores de DNS. Cada endereço precisa estar no formato IP_ADDR ou IP_ADDR:PORT e ser separado por ponto e vírgula (;). Para IP_ADDR, a porta DNS 52 padrão será usada. Por exemplo: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000. Se esta configuração não for definida, o ESPv2 usará o resolvedor padrão configurado em /etc/resolv.conf
--backend_dns_lookup_family	Defina a família de busca DNS para todos os back-ends. As opções são auto, v4only, v6only, v4preferred e all. O padrão é v4preferred. auto é um valor legado. Definir a flag como auto vai resultar em um comportamento equivalente a v6preferred.
--non_gcp	Por padrão, o proxy tenta se conectar ao Google Cloud Metadata Server para ter acesso à localização da VM nas primeiras solicitações. Para pular essa etapa, defina a sinalização como true.

Teste local

É possível implantar o ESPv2 localmente na sua estação de trabalho para teste. Consulte Como executar o ESP localmente ou em outra plataforma para mais detalhes.

Use essas flags com as flags de implantação fora do Google Cloud para facilitar a implantação local e os testes em integração contínua.

Sinalização	Descrição
--service_json_path	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.
--enable_backend_address_override	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.).

Extração de IP do cliente

Use essas sinalizações para configurar a extração de IP do cliente no ESPv2.

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

Suporte ao CORS

Consulte Suporte ao CORS para ver uma descrição das opções de suporte ao CORS disponíveis. Nesta seção, você verá como usar sinalizações de inicialização do ESPv2 para aceitar o CORS.

Para ativar o suporte ao CORS no ESPv2, inclua a opção --cors_preset e defina uma das seguintes sinalizações:

• --cors_preset=basic
• --cors_preset=cors_with_regex

Quando você inclui --cors_preset=basic ou --cors_preset=cors_with_regex, o ESPv2:

• presume que todos os caminhos de localização têm a mesma política de CORS;
• responde a solicitações simples e solicitações HTTP OPTIONS comprovadas;
• armazena em cache o resultado da solicitação OPTIONS de simulação por até 20 dias (1.728.000 segundos);

• define os cabeçalhos de resposta para os valores:

  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
  Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
  Access-Control-Expose-Headers: Content-Length,Content-Range
  Access-Control-Max-Age: 1728000

Para substituir o valor padrão de Access-Control-Allow-Origin, especifique uma das opções abaixo:

Opção	Descrição
--cors_allow_origin	Use com --cors_preset=basic para definir Access-Control-Allow-Origin para uma origem específica. Exemplo: --cors_preset=basic --cors_allow_origin=http://example.com
--cors_allow_origin_regex	Use com --cors_preset=cors_with_regex. Permite que você use uma expressão regular para definir Access-Control-Allow-Origin. Exemplo: --cors_preset=cors_with_regex --cors_allow_origin_regex=^https?://.+\.example\.com$ 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: "--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$" 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]

Depois de definir --cors_preset=basic ou --cors_preset=cors_with_regex para ativar o CORS, substitua os valores padrão dos outros cabeçalhos de resposta. Para isso, especifique uma ou mais das opções a seguir:

Opção	Descrição
--cors_allow_methods	Define Access-Control-Allow-Methods para os métodos HTTP especificados. Especifique os métodos HTTP como uma string com cada método HTTP separado por uma vírgula. Exemplo: --cors_preset=basic --cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers	Define Access-Control-Allow-Headers para os cabeçalhos HTTP especificados. Especifique os cabeçalhos HTTP como uma cadeia com cada cabeçalho HTTP separado por uma vírgula. Exemplo: --cors_preset=basic --cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials	Inclui o cabeçalho Access-Control-Allow-Credentials (em inglês) com o valor true nas respostas. Por padrão, o cabeçalho Access-Control-Allow-Credentials não é incluído nas respostas. Exemplo: --cors_preset=basic --cors_allow_credentials
--cors_expose_headers	Define Access-Control-Expose-Headers para os cabeçalhos especificados. Especifique quais cabeçalhos podem ser expostos como parte da resposta como uma string com cada cabeçalho separado por uma vírgula. Exemplo: --cors_preset=basic --cors_expose_headers=Content-Length
--cors_max_age	Define Access-Control-Max-Age com a duração de tempo especificada. O formato aceitável é uma sequência de números decimais, cada um com um valor fracionário opcional e um sufixo de unidade, como "300m", "1,5h" ou "2h45m". As unidades de tempo válidas são "m" para minutos e "h" para horas. O valor padrão será "480h" se não tiver sido definido. Exemplo: --cors_preset=basic --cors_max_age=24h

Suporte TLS

Use estas sinalizações para configurar o ESPv2 para usar conexões TLS.

Bandeira	Descrição
--ssl_server_cert_path	Caminho do certificado do servidor proxy. Quando configurado, o ESPv2 aceita apenas conexões seguras HTTP/1.x e HTTP/2 em listener_port. Exige os arquivos de certificado e de chave "server.crt" e "server.key" nesse caminho.
--ssl_server_cipher_suites	Pacotes de criptografia a serem usados para conexões downstream, especificados como uma lista separada por vírgulas. Consulte a configuração do pacote de criptografia.
--ssl_backend_client_cert_path	Caminho do certificado do cliente do proxy. Quando configurado, o ESPv2 ativa a autenticação TLS mútua para back-ends HTTPS. Exige os arquivos de certificado e de chave "client.crt" and "client.key" nesse caminho.
--ssl_backend_client_root_certs_file	O caminho do arquivo de certificados raiz que o ESPv2 usa para verificar o certificado do servidor de back-end. Se não for especificado, o ESPv2 usará "/etc/ssl/certs/ca-certificates.crt" por padrão.
--ssl_backend_client_cipher_suites	Pacotes de criptografia a serem usados para back-ends HTTPS, especificados como uma lista separada por vírgulas. Consulte a configuração do pacote de criptografia.
--ssl_minimum_protocol	Versão mínima do protocolo TLS para conexão do lado do cliente. Consulte este artigo (em inglês).
--ssl_maximum_protocol	Versão máxima do protocolo TLS para conexão do lado do cliente. Consulte este artigo (em inglês).
--enable_strict_transport_security	Ativa o HSTS (Segurança de transporte restrito HTTP). O cabeçalho de resposta "Strict-Transport-Security" com o valor "max-age=31536000; includeSubdomains;" é adicionado a todas as respostas.
--generate_self_signed_cert	Gere um certificado e uma chave assinados automaticamente no início e armazena-os em "/tmp/ssl/endpoints/server.crt" e "/tmp/ssl/endpoints/server.key". Isso é útil quando apenas um certificado de assinatura automática aleatória for necessário para exibir solicitações HTTPS. O certificado gerado terá o nome comum "localhost" e será válido por 10 anos.

Tempo limite e novas tentativas

Use estas sinalizações para configurar o tempo limite remoto da chamada HTTP e outras tentativas do ESPv2.

Bandeira	Descrição
--http_request_timeout_s	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.
--service_control_network_fail_open	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.
--service_control_check_timeout_ms	Define o tempo limite em milissegundos da solicitação de verificação de controle de serviço. Precisa ser > 0, e o padrão será de 1000 se não estiver definido.
--service_control_report_timeout_ms	Define o tempo limite em milissegundos da solicitação de relatório de controle de serviço. Precisa ser > 0, e o padrão será de 1000 se não estiver definido.
--service_control_quota_timeout_ms	Define o tempo limite em milissegundos da solicitação de cota de controle de serviço. Precisa ser > 0, e o padrão será 1000 se não estiver definido.
--service_control_check_retries	Define a quantidade de novas tentativas da solicitação de verificação de controle de serviço. Precisa ser >= 0, e o padrão será 3 se não estiver definido.
--service_control_report_retries	Define os tempos de repetição da solicitação de relatório do controle de serviço. Precisa ser >= 0, e o padrão será 5 se não estiver definido.
--service_control_quota_retries	Define a quantidade de novas tentativas da solicitação de cota de controle de serviço. Precisa ser >= 0, e o padrão será 1, se não estiver definido.
--backend_retry_ons	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
--backend_retry_num	O número permitido de novas tentativas. Precisa ser >= 0, e o padrão é 1.

Transcodificação do gRPC

Use estas sinalizações para configurar o ESPv2 para transcodificação de HTTP/JSON para gRPC.

Bandeira	Descrição
--transcoding_always_print_primitive_fields	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.
--transcoding_always_print_enums_as_ints	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.
--transcoding_stream_newline_delimited	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 para uma matriz JSON.
--transcoding_case_insensitive_enum_parsing	Normalmente, os valores de enumeração proto precisam estar em letras maiúsculas quando usados no JSON. Defina essa flag como verdadeira se a solicitação JSON usar valores de enumeração não em maiúsculas.
--transcoding_preserve_proto_field_names	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.
--transcoding_ignore_query_parameters	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.
--transcoding_ignore_unknown_query_parameters	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.
--transcoding_query_parameters_disable_unescape_plus	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.

Modificação de solicitação e resposta

Use estas sinalizações para configurar o ESPv2 para modificar parcialmente solicitações e respostas.

Bandeira	Descrição
--add_request_header	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.
--append_request_header	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.
--add_response_header	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.
--append_response_header	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.

Opções de segurança

Use essas sinalizações para refinar ainda mais as solicitações permitidas pelo ESPv2.

Bandeira	Descrição
--underscores_in_headers	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.
--envoy_connection_buffer_limit_bytes	Configure a quantidade máxima de dados em buffer para cada corpo de solicitação/resposta em bytes. Quando não definido, o padrão é decidido pelo Envoy. Consulte a configuração do listener do Envoy.
--disable_normalize_path	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.
--disable_merge_slashes_in_path	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.
--disallow_escaped_slashes_in_path	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.

Autenticação JWT

Use estas sinalizações para configurar o ESPv2 e buscar Jwks remotos com novas tentativas.

Bandeira	Descrição
--jwks_fetch_num_retries	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.
--jwks_fetch_retry_back_off_base_interval_ms	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.
--jwks_fetch_retry_back_off_max_interval_ms	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.
--jwks_cache_duration_in_s	Especifica a duração do cache da chave pública do JWT em segundos. O padrão é 5 minutos, se não for definido.
--jwks_async_fetch_fast_listener	Só se aplica quando a flag --disable_jwks_async_fetch não está definida. Essa flag determina se o ESPv2 vai aguardar a conclusão da busca inicial de jwks antes de vincular a porta do listener. Se for falso, ele vai esperar. O padrão é "false".
--jwt_cache_size	Especifique o número de tokens JWT exclusivos como o tamanho máximo do cache do JWT. O cache armazena apenas tokens verificados. Se for 0, o cache JWT será desativado. Essa flag limita o uso de memória para o cache JWT. A memória usada pelo cache é aproximadamente (tamanho do token + 64 bytes) por token. Se não for especificado, o padrão será 100000.
--disable_jwt_audience_service_name_check	Normalmente, o campo aud do JWT é verificado em relação aos públicos 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 flag for usada, o campo aud do JWT não será verificado.

A seguir

Saiba mais sobre:

• Migrar para o Extensible Service Proxy V2
• Extensões da OpenAPI