Opções de arranque do proxy de serviço extensível V2

OpenAPI   |  gRPC

O proxy de serviço extensível V2 (ESPv2) é um proxy baseado no Envoy que permite que os Cloud Endpoints ofereçam funcionalidades de gestão de APIs. Para configurar o ESPv2, pode especificar flags de configuração ao implementar o serviço ESPv2.

Definir sinalizações de configuração

O método de definição das flags de configuração do ESPv2 varia consoante a plataforma de implementação, conforme descrito nas secções seguintes.

VM do Compute Engine

Os sinalizadores de configuração do ESPv2 para o Compute Engine são especificados 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 flags de configuração do ESPv2.

GKE e Kubernetes

Pode especificar flags de configuração para o GKE e o Kubernetes no campo args do ficheiro de manifesto de implementaçã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 flags de configuração do ESPv2.

Cloud Run para plataformas sem servidor

Para especificar opções de início para o Cloud Run para sem servidor, use a variável de ambiente ESPv2_ARGS. A variável pode ser definida no comando gcloud run deploy através da 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 flag 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 esse delimitador para separar vários argumentos. Não use uma vírgula como delimitador. Coloque o delimitador personalizado no início da variável de ambiente ESPv2_ARGS, entre acentos circunflexos.

O exemplo seguinte 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 flag que está a definir contiver vírgulas, tem de definir a variável de ambiente ESPv2_ARGS no script gcloud_build_image.

Por exemplo, para adicionar a bandeira --cors_allow_methods=PUT,POST,GET:

• Transfira o script gcloud_build_image.
• Edite o gcloud_build_image conforme 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

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

Sinalizações de configuração do ESPv2

As flags de configuração do ESPv2 podem ser agrupadas nas seguintes categorias:

• Configuração sem servidor
• Registo
• Rastreio
• Verificação de saúde
• Depuração
• Testes locais
• NãoGoogle Cloud utilização
• Extração do IP do cliente
• Compatibilidade com CORS
• Suporte de TLS
• Limite de tempo e novas tentativas
• Transcodificação gRPC
• Modificação de pedidos e respostas
• Opções de segurança
• Autenticação JWT

Pode encontrar exemplos genéricos adicionais e texto de ajuda para flags do ESPv2 no repositório do GitHub.

Configuração sem servidor

Estas flags são necessárias para executar o ESPv2 em plataformas sem servidor, como o GKE, o Compute Engine e o Kubernetes. Não podem ser definidas quando implementadas no Cloud Run para plataformas sem servidor.

Nota: para utilizadores do Kubernetes, NÃO coloque aspas à volta dos valores dos campos nos ficheiros de configuração. Por exemplo, --cors_allow_origin="http://example.com" atribui o valor de string \"http://example.com\" ao campo cor_allow_origin em vez do valor de string pretendido http://example.com.

``

Bandeira	Descrição
--service	Define o nome do serviço Endpoints.
--version	Define o ID da configuração do serviço do serviço Endpoints.
--rollout_strategy	Especifica a estratégia de implementação da configuração do serviço, [fixed|managed]. A predefinição é fixed.
--listener_port	Identifica a porta para aceitar ligações a jusante. Suporta ligações HTTP/1.x, HTTP/2 e gRPC. A predefinição é 8080.
--backend	Especifica o endereço do servidor de aplicações de back-end local. Os esquemas válidos são http, https, grpc e grpcs se incluídos. O esquema predefinido é >http.

Registo

Use estas flags para configurar o ESPv2 de modo a escrever informações adicionais no registo do Stackdriver.

Bandeira	Descrição
--log_request_headers	Registe os valores dos cabeçalhos de pedidos especificados, separados por vírgulas sem espaços. Por exemplo, defina este sinalizador como: --log_request_headers=foo,bar Se os valores do cabeçalho "foo" e "bar" estiverem disponíveis no pedido, o registo de pontos finais contém: request_headers: foo=foo_value;bar=bar_value
--log_response_headers	Registe os valores dos cabeçalhos de resposta especificados, separados por vírgulas sem espaços. Por exemplo, defina este sinalizador como: --log_response_headers=baz,bing Se os valores do cabeçalho "baz" e "bing" estiverem disponíveis na resposta, o registo de pontos finais contém: response_headers: baz=baz_value;bing=bing_value
--log_jwt_payloads	Registe os valores dos campos primitivos de payload JWT especificados, separados por vírgulas sem espaços. Por exemplo, defina este sinalizador como: --log_jwt_payloads=sub,project_id,foo.foo_name Se os valores estiverem disponíveis no payload JWT, o registo de pontos finais contém: jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value Os valores na carga útil do JWT têm de ser campos primitivos (string, número inteiro). Os objetos e as matrizes JSON não são registados.
--access_log	Se for especificado, o caminho para o ficheiro local onde as entradas do registo de acesso vão ser escritas.
--access_log_format	Formato de string para especificar o formato do registo de acesso. Se não estiver definida, é usada a >string de formato predefinida. Para ver a gramática de formato detalhada, consulte a referência de strings de formato.

Rastreio

Use estas flags para configurar os dados de rastreio do ESPv2 enviados para o Stackdriver. Estas flags só se aplicam quando o rastreio está ativado.

Bandeira	Descrição
--disable_tracing	Desative o rastreio. Por predefinição, a monitorização está ativada. Quando ativado, o ESPv2 faz uma amostragem de um pequeno número de pedidos à sua API a cada segundo para obter rastreios que envia para o Stackdriver Trace. Por predefinição, é feita uma amostragem de 1 em cada 1000 pedidos. Use a flag --tracing_sample_rate para alterar a taxa de amostragem.
--tracing_project_id	O ID do projeto Google para o Stackdriver Tracing. O rastreio é um serviço pago. O projeto especificado é faturado pela monitorização. Por predefinição, o ID do projeto do serviço ESPv2 implementado é faturado. O ID do projeto é determinado através da chamada do Google Cloud servidor de metadados da instância no arranque. Se o ESPv2 for implementado fora do Google Cloud (usando a flag --non_gcp ), a monitorização é desativada automaticamente, a menos que esta flag seja explicitamente definida.
--tracing_sample_rate	Defina a taxa de amostragem de rastreio para um valor entre 0,0 e 1,0. Este valor especifica a fração de pedidos que são amostrados. O valor predefinido é 0,001, o que equivale a 1 em 1000 pedidos.
--tracing_incoming_context	Esta flag especifica os cabeçalhos HTTP a verificar para o contexto de rastreio, com valores de flags separados por vírgulas sem espaços. Tenha em atenção que a ordem é importante: o contexto do rastreio é derivado do primeiro cabeçalho que corresponder. Os valores possíveis incluem traceparent, x-cloud-trace-context e grpc-trace-bin. Se for omitido, os cabeçalhos traceparent e x-cloud-trace-context são verificados (por ordem). Consulte o artigo Monitorizar a sua API para ver mais detalhes.
--tracing_outgoing_context	Define o cabeçalho do contexto de rastreio no pedido enviado para o serviço de back-end. Esta flag especifica o cabeçalho HTTP a definir, com valores de flags separados por vírgulas sem espaços. Os valores possíveis incluem traceparent, x-cloud-trace-context e grpc-trace-bin. Se for omitido, são enviados os cabeçalhos traceparent e x-cloud-trace-context. Consulte o artigo Monitorizar a sua API para ver mais detalhes.

Verificação de funcionamento

Use estas flags para configurar as verificações de funcionamento para o ESPv2. A primeira flag pode ser usada para configurar um controlador de saúde para responder às chamadas de verificação de saúde. As outras flags podem ser usadas para ativar a verificação do estado de funcionamento para o back-end gRPC.

/tbody>

Bandeira	Descrição
-z, --healthz	Defina um ponto final de verificação de funcionamento. Por exemplo, -z healthz faz com que o ESPv2 devolva o código 200 para o caminho /healthz.
--health_check_grpc_backend	Ative o ESPv2 para verificar periodicamente o serviço de funcionamento do gRPC para um back-end especificado pela flag --backend. O back-end tem de usar o protocolo gRPC e implementar o protocolo de verificação de funcionamento gRPC. O ponto final da verificação de funcionamento ativado pela flag --healthz reflete o resultado da verificação de funcionamento do back-end.
--health_check_grpc_backend_service	Especifique o nome do serviço quando chamar o protocolo de verificação de estado gRPC de back-end. O valor desta flag só é aplicado quando a flag --health_check_grpc_backend é usada. É opcional. Se não for definido, a predefinição é vazio. Um nome de serviço vazio destina-se a consultar o estado de funcionamento geral do servidor gRPC.
--health_check_grpc_backend_interval	Especifique o intervalo de verificação e o limite de tempo do pedido ao chamar o serviço de saúde gRPC de back-end. O valor desta flag só é aplicado quando a flag --health_check_grpc_backend é usada. A predefinição é 1 segundo. O formato aceite é 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.

Depuração

Use estas flags para configurar a depuração do ESPv2. Estes sinalizadores podem ser usados para configurar uma porta de administrador do Envoy para obter a configuração e as estatísticas ou executar o Envoy no modo de depuração para escrever informações ao nível da depuração no registo.

Bandeira	Descrição
--status_port, --admin_port	Ative a administração do ESPv2 Envoy nesta porta. Consulte a referência da interface de administração do Envoy para ver mais detalhes. A porta de administração está desativada por predefinição.
--enable_debug	Ative os registos ao nível de depuração e adicione cabeçalhos de depuração.

Non-Google Cloud Deployment

Se o ESPv2 for implementado num ambiente que não seja de produção, podem ser necessárias as seguintes flags. Google Cloud

Bandeira	Descrição
--service_account_key	Especifica o ficheiro JSON da chave da conta de serviço para aceder aos serviços Google. Se a opção for omitida, o proxy contacta o Google Cloud servidor de metadados para obter um token de acesso.
--dns_resolver_addresses	As moradas dos resolvedores de DNS. Cada endereço deve estar no formato IP_ADDR ou IP_ADDR:PORT e estar separado por um ponto e vírgula (;). Para IP_ADDR, é usada a porta DNS predefinida 52. Por exemplo: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) Se não estiver definida, o ESPv2 usa o resolvedor predefinido configurado em /etc/resolv.conf
--backend_dns_lookup_family	Defina a família de procura de DNS para todos os backends. As opções são auto, v4only, v6only, v4preferred e all. A predefinição é v4preferred. Tenha em atenção que auto é um valor antigo. Se definir a flag como auto, o comportamento é equivalente a v6preferred.
--non_gcp	Por predefinição, o proxy tenta estabelecer ligação ao Google Cloud servidor de metadados para obter a localização da VM nos primeiros pedidos. Para ignorar este passo, defina esta flag como true.

Testes locais

O ESPv2 pode ser implementado localmente na sua estação de trabalho para testes. Consulte o artigo Executar o ESP localmente ou noutra plataforma para mais detalhes.

Use estas flags juntamente com as flags de nãoGoogle Cloud implementação para uma implementação e testes locais mais fáceis na integração contínua.

Bandeira	Descrição
--service_json_path	Especifique um caminho para o ESPv2 carregar a configuração do serviço de endpoint. Com este sinalizador, o ESPv2 usa uma estratégia de implementação "fixa" e os seguintes sinalizadores são ignorados: --service --version --rollout_strategy Esta flag impede que o ESPv2 use a quota da API Service Management.
--enable_backend_address_override	Os endereços de back-end podem ser especificados através da flag --backend ou do campo backend.rule.address na configuração do serviço. Para os utilizadores da OpenAPI, tenha em atenção que o campo backend.rule.address é definido pelo campo address na extensão x-google-backend. Normalmente, a configuração do serviço por operação backend.rule.address é especificada para o encaminhamento sem servidor. Por predefinição, o elemento backend.rule.address tem prioridade sobre o indicador --backend para cada operação individual. Ative esta flag se quiser que a flag --backend tenha prioridade. Isto é útil se estiver a desenvolver numa estação de trabalho local. Em seguida, pode usar a mesma configuração do serviço de produção, mas substituir o endereço do backend através do sinalizador --backend para testes locais. Nota: apenas o endereço é substituído. Todos os outros componentes de backend.rule continuam a aplicar-se (prazos, autorização de back-end, tradução de caminhos, etc.).

Extração do IP do cliente

Use estas flags para configurar a extração do IP do cliente para o ESPv2.

Bandeira	Descrição
--envoy_use_remote_address	Configuração do Envoy HttpConnectionManager, consulte a referência do Envoy para ver informações detalhadas. A predefinição é desativada.
--envoy_xff_num_trusted_hops	Configuração do Envoy HttpConnectionManager, consulte a referência do Envoy para ver informações detalhadas. O valor predefinido é 2.

Compatibilidade com CORS

Consulte o artigo Compatibilidade com CORS para ver uma descrição das opções de compatibilidade com CORS disponíveis. Esta secção descreve a utilização de flags de arranque do ESPv2 para suportar CORS.

Para ativar o suporte de CORS no ESPv2, inclua a opção --cors_preset e defina-a como um dos seguintes flags:

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

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

• Assume que todos os caminhos de localização têm a mesma política de CORS.
• Responde a pedidos simples e a pedidos de pré-envio HTTP OPTIONS.
• Coloca em cache o resultado do pedido de verificação prévia OPTIONS durante um máximo de 20 dias (1728000 segundos).

• Define os cabeçalhos das respostas para os seguintes 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 predefinido de Access-Control-Allow-Origin, especifique uma das seguintes opções:

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 usar 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 define esta opção num ficheiro de configuração do Kubernetes, tem de adicionar um caráter de barra invertida adicional para ignorar ambas as instâncias de \ na string, por exemplo: "--cors_preset","cors_with_regex", "--cors_allow_origin_regex","^https?://.+\\.example\\.com$" Quando define esta opção no script gcloud_build_image para o Cloud Run, tente evitar usar carateres com escape e barras invertidas, pois podem não ser transmitidos corretamente do script bash para o proxy no arranque. Use classes de carateres em vez de metasequências. Por exemplo: Original: \d Recommended: [0-9]

Depois de definir --cors_preset=basic ou --cors_preset=cors_with_regex para ativar o CORS, pode substituir os valores predefinidos dos outros cabeçalhos de resposta especificando uma ou mais das seguintes opções:

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 string 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 com o valor true nas respostas. Por predefinição, o cabeçalho Access-Control-Allow-Credentials não está 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 que 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 para a duração 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 "300 m", "1,5 h" ou "2 h 45 m". As unidades de tempo válidas são "m" para minutos e "h" para horas. O valor predefinido é "480h" se não for definido. Exemplo: --cors_preset=basic --cors_max_age=24h

Suporte de TLS

Use estas flags para configurar o ESPv2 de modo a usar ligações TLS.

Bandeira	Descrição
--ssl_server_cert_path	Caminho do certificado do servidor do proxy. Quando configurado, o ESPv2 só aceita ligações HTTP/1.x e HTTP/2 seguras em listener_port. Requer os ficheiros de certificado e chave "server.crt" e "server.key" neste caminho.
--ssl_server_cipher_suites	Conjuntos de cifras a usar para ligações a jusante, especificados como uma lista separada por vírgulas. Consulte a Configuração do conjunto de cifras.
--ssl_backend_client_cert_path	Caminho do certificado do cliente do proxy. Quando configurado, o ESPv2 ativa a autenticação mútua TLS para backends HTTPS. Requer os ficheiros de certificado e chave "client.crt" e "client.key" neste caminho.
--ssl_backend_client_root_certs_file	O caminho do ficheiro dos certificados de raiz que o ESPv2 usa para validar o certificado do servidor de back-end. Se não for especificado, o ESPv2 usa "/etc/ssl/certs/ca-certificates.crt" por predefinição.
--ssl_backend_client_cipher_suites	Conjuntos de cifras a usar para back-ends HTTPS, especificados como uma lista separada por vírgulas. Consulte a Configuração do conjunto de cifras.
--ssl_minimum_protocol	Versão mínima do protocolo TLS para a ligação do lado do cliente. Consulte este
--ssl_maximum_protocol	Versão máxima do protocolo TLS para a ligação do lado do cliente. Consulte este
--enable_strict_transport_security	Ative a HSTS (HTTP Strict Transport Security). 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 autoassinados no início e, em seguida, armazene-os em "/tmp/ssl/endpoints/server.crt" e "/tmp/ssl/endpoints/server.key". Isto é útil quando só é necessário um certificado autoassinado aleatório para publicar pedidos HTTPS. O certificado gerado tem o nome comum "localhost" e é válido durante 10 anos.

Limite de tempo e novas tentativas

Use estas flags para configurar o limite de tempo e as repetições de chamadas HTTP remotas para o ESPv2.

Bandeira	Descrição
--http_request_timeout_s	Defina o limite de tempo em segundos para pedidos feitos a serviços externos, exceto o back-end e o Google Service Control. Inclui o Google ServiceManagement, o servidor de metadados e o servidor Google IAM. Tem de ser > 0 e a predefinição é 30 segundos se não for definida.
--service_control_network_fail_policy	Em caso de falhas de rede ao estabelecer ligação ao controlo de serviços Google, os pedidos são permitidos se esta flag estiver aberta. A predefinição é open (abrir).
--service_control_check_timeout_ms	Defina o limite de tempo em milissegundos para o pedido de verificação do controlo de serviços. Tem de ser > 0 e a predefinição é 1000 se não for definida.
--service_control_report_timeout_ms	Defina o limite de tempo em milissegundos para o pedido de relatório de controlo de serviços. Tem de ser > 0 e a predefinição é 1000 se não for definida.
--service_control_quota_timeout_ms	Defina o limite de tempo em milissegundos para o pedido de quota de controlo de serviços. Tem de ser > 0 e a predefinição é 1000 se não for definida.
--service_control_check_retries	Defina o número de tentativas para o pedido de verificação do controlo de serviços. Tem de ser >= 0 e a predefinição é 3 se não for definida
--service_control_report_retries	Defina as tentativas para o pedido de relatório de controlo de serviços. Tem de ser >= 0 e a predefinição é 5 se não for definida
--service_control_quota_retries	Defina o número de tentativas para o pedido de quota de controlo de serviço. Tem de ser >= 0 e a predefinição é 1 se não for definido
--backend_retry_ons	As condições em que o ESPv2 tenta novamente nos back-ends. Pode especificar uma ou mais condições usando uma lista separada por vírgulas.retryOn A predefinição é reset,connect-failure,refused-stream. Desative a repetição definindo esta flag como vazia. Consulte os seguintes links para ver as condições aceites: x-envoy-retry-on x-envoy-retry-grpc-on
--backend_retry_num	O número permitido de novas tentativas. Tem de ser >= 0 e a predefinição é 1.

Transcodificação gRPC

Use estas flags para configurar o ESPv2 para a transcodificação de HTTP/JSON para gRPC.

Bandeira	Descrição
--transcoding_always_print_primitive_fields	Especifica se os campos primitivos devem ser impressos para a transcodificação grpc-json. Por predefinição, os campos primitivos com valores predefinidos são omitidos na saída JSON. Por exemplo, um campo int32 definido como 0 é omitido. Definir esta flag como verdadeira substitui o comportamento predefinido e imprime campos primitivos independentemente dos respetivos valores. A predefinição é false.
--transcoding_always_print_enums_as_ints	Especifica se os enums devem ser impressos como ints para a transcodificação grpc-json. Por predefinição, são renderizados como strings. A predefinição é false.
--transcoding_stream_newline_delimited	Se for verdadeiro, use o delimitador de nova linha para separar as mensagens de streaming de resposta. Se for falso, todas as mensagens de streaming de respostas são transcodificadas numa matriz JSON.
--transcoding_case_insensitive_enum_parsing	Normalmente, os valores de enumeração proto devem estar em maiúsculas quando usados em JSON. Defina esta flag como verdadeira se o seu pedido JSON usar valores de enumeração que não estejam em maiúsculas.
--transcoding_preserve_proto_field_names	Especifica se os nomes dos campos proto devem ser preservados para a transcodificação grpc-json. Por predefinição, o protobuf gera nomes de campos JSON com a opção json_name ou com letras minúsculas e maiúsculas alternadas, nessa ordem. A definição desta flag preserva os nomes dos campos originais. A predefinição é false.
--transcoding_ignore_query_parameters	Uma lista de parâmetros de consulta separados por vírgulas a ignorar para o mapeamento do método de transcodificação na transcodificação grpc-json. Por predefinição, o filtro de transcodificação não transcodifica um pedido com parâmetros de consulta desconhecidos/inválidos.
--transcoding_ignore_unknown_query_parameters	Especifica se devem ser ignorados os parâmetros de consulta que não podem ser mapeados para um campo protobuf correspondente na transcodificação grpc-json. Use esta opção se não conseguir controlar os parâmetros de consulta e não os conhecer antecipadamente. Caso contrário, use --transcoding_ignore_query_parameters. A predefinição é false.
--transcoding_query_parameters_disable_unescape_plus	Por predefinição, os sinais de mais "+" nos parâmetros de consulta não são escapados para espaço " " na transcodificação grpc-json. Isto destina-se a suportar o HTML 2.0. Se não for desejável, defina esta flag como verdadeira para desativar esta funcionalidade.

Modificação de pedidos e respostas

Use estas flags para configurar o ESPv2 de modo a modificar parcialmente os pedidos e as respostas.

Bandeira	Descrição
--add_request_header	Adicione um cabeçalho HTTP ao pedido antes de o enviar para o back-end a montante. Se o cabeçalho já estiver no pedido, o respetivo valor é substituído pelo novo. Suporta variáveis personalizadas do Envoy. Este 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 ao pedido antes de o enviar para o back-end a montante. Se o cabeçalho já estiver no pedido, o novo valor é anexado. Suporta variáveis personalizadas do Envoy. Este 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	Adicionar um cabeçalho HTTP à resposta antes de a enviar ao cliente a jusante. Se o cabeçalho já estiver na resposta, é substituído pelo novo. Suporta variáveis personalizadas do Envoy. Este 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 a enviar ao cliente a jusante. Se o cabeçalho já estiver na resposta, o novo é anexado. Suporta variáveis personalizadas do Envoy. Este 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 estas flags para refinar ainda mais os pedidos que o ESPv2 permite.

Bandeira	Descrição
--underscores_in_headers	Permitir a passagem de nomes de cabeçalhos que contenham sublinhados. A predefinição é false. O caráter de sublinhado é permitido nos nomes dos cabeçalhos pela RFC-7230. No entanto, este comportamento é implementado como uma medida de segurança porque alguns sistemas tratam _ e - como intermutáveis.
--envoy_connection_buffer_limit_bytes	Configure a quantidade máxima de dados que são colocados em buffer para cada corpo de pedido/resposta, em bytes. Se não estiver definido, o valor predefinido é decidido pelo Envoy. Consulte a configuração do ouvinte do Envoy.
--disable_normalize_path	Desative a normalização do cabeçalho HTTP path de acordo com o RFC 3986. Recomendamos que mantenha esta opção ativada se o seu back-end realizar a normalização do caminho por predefinição. A tabela seguinte fornece exemplos do pedido que o back-end recebe do ESPv2 com base na configuração desta flag.path ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello/../world | Rejected | /world | | /%4A | /%4A | /J | | /%4a | /%4a | /J | ----------------------------------------------------------------- Por predefinição, o ESPv2 normaliza os caminhos. Desative a funcionalidade apenas se o seu tráfego for afetado pelo comportamento. Nota: de acordo com a RFC 3986, esta opção não anula a escape de carateres de barra invertida codificados em percentagem. Consulte a flag --disallow_escaped_slashes_in_path para ativar este comportamento não conforme. Nota: a normalização de maiúsculas e minúsculas da RFC 3986 não é suportada, mesmo que esta opção esteja ativada. Para mais detalhes, consulte o artigo Compreender a criação de modelos de caminhos.
--disable_merge_slashes_in_path	Desative a união de barras invertidas adjacentes no cabeçalho HTTP path. Recomendamos que mantenha esta opção ativada se o seu back-end realizar a união por predefinição. A tabela seguinte fornece exemplos do pedido que o back-end recebe do ESPv2 com base na configuração desta flag.path ----------------------------------------------------------------- | Request Path | Without Normalization | With Normalization | ----------------------------------------------------------------- | /hello//world | Rejected | /hello/world | | /hello/// | Rejected | /hello | ----------------------------------------------------------------- Por predefinição, o ESPv2 une as barras invertidas. Desative a funcionalidade apenas se o seu tráfego for afetado pelo comportamento. Para mais detalhes, consulte o artigo Compreender a criação de modelos de caminhos.
--disallow_escaped_slashes_in_path	Não permite pedidos com carateres de barra codificados em percentagem com carateres de escape: %2F ou %2f é tratado como / %5C ou %5c é tratado como \ Quando ativado, o comportamento depende do protocolo usado: Para backends da OpenAPI, os caminhos de pedidos com barras invertidas com codificação percentual escapadas são automaticamente não escapados através de um redirecionamento. Para back-ends gRPC, os caminhos de pedidos com barras invertidas com codificação percentual escapadas são rejeitados (o gRPC não suporta redirecionamentos). Esta opção não está em conformidade com a RFC 3986, pelo que está desativada por predefinição. Se o seu back-end não estiver em conformidade com a RFC 3986 e escapar às barras invertidas, tem de ativar esta opção no ESPv2. Isto impede ataques de confusão de caminhos que resultam na não aplicação dos requisitos de segurança. Para mais detalhes, consulte o artigo Compreender a criação de modelos de caminhos.

Autenticação JWT

Use estas flags para configurar o ESPv2 de modo a obter Jwks remotos com novas tentativas.

Bandeira	Descrição
--jwks_fetch_num_retries	Especifique o número de novas tentativas na política de novas tentativas de obtenção de JWKS remota. A predefinição é 0, não repetir.
--jwks_fetch_retry_back_off_base_interval_ms	Especifique o intervalo base de retirada exponencial de novas tentativas de obtenção de JWKS, em milissegundos. A predefinição é 200 ms, se não for definida.
--jwks_fetch_retry_back_off_max_interval_ms	Especifique o intervalo máximo de retirada exponencial de novas tentativas de obtenção de JWKS, em milissegundos. A predefinição é 32 segundos, se não for definida.
--jwks_cache_duration_in_s	Especifique a duração da cache da chave pública JWT em segundos. A predefinição é 5 minutos, se não estiver definida.
--jwks_async_fetch_fast_listener	Só se aplica quando a flag --disable_jwks_async_fetch não está definida. Esta flag determina se o ESPv2 vai aguardar a conclusão da obtenção jwks inicial antes de associar a porta do ouvinte. Se for falso, aguarda. O valor predefinido é False.
--jwt_cache_size	Especifique o número de tokens JWT únicos como o tamanho máximo da cache JWT. A cache apenas armazena tokens validados. Se for 0, a cache JWT está desativada. Esta flag limita a utilização de memória para a cache JWT. A memória usada pela cache é aproximadamente (tamanho do token + 64 bytes) por token. Se não for especificado, o valor predefinido é 100 000.
--disable_jwt_audience_service_name_check	Normalmente, o campo aud JWT é verificado em relação aos públicos-alvo especificados no campo x-google-audiences OpenAPI. Este sinalizador altera o comportamento quando o campo x-google-audiences não é especificado. Quando o campo x-google-audiences não é especificado e esta flag não é usada, o nome do serviço é usado para verificar o campo aud do JWT. Se este sinalizador for usado, o campo aud do JWT não é verificado.

O que se segue?

Saiba mais acerca do:

• Migre para o proxy de serviço extensível V2
• Extensões da OpenAPI