Esta página foi traduzida pela API Cloud Translation.
Switch to English

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

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 obter 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
  • 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

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.

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.

Sinalização 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.

Sinalização 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 código do projeto é determinado chamando o servidor de metadados da instância do GCP na inicialização. Se o ESPv2 for implantado fora do GCP (usando a sinalização --non_gcp), o rastreamento será desativado automaticamente, a menos que essa sinalização 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.

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

Se omitido, o cabeçalho traceparent será verificado.

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 omitido, o cabeçalho traceparent será enviado.

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

Como depurar

Use essas sinalizações para configurar verificações de integridade e depuração para o ESPv2. Esses sinalizadores podem ser usados para configurar um gerenciador de integridade para responder a chamadas de verificação de integridade, para uma porta de administrador do Envoy de busca de configurações e estatísticas ou para executar o Envoy no modo de depuração para gravar informações de nível de depuração no registro.

Sinalização 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.
--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 da plataforma GCP

Se o ESPv2 for implantado em um ambiente que não seja do Google Cloud Platform (GCP), as sinalizações 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 GCP para buscar um token de acesso.

--dns_resolver_addresses Endereços de resolvedores do 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 Define a família de pesquisa dns de todos os back-ends. As opções são auto, v4only e v6only. O padrão é autocode>.
--non_gcp Por padrão, o proxy tenta se conectar ao GCP Metadata Server para ter acesso à localização da VM nas primeiras solicitações. Para pular essa etapa, defina a sinalização como true.

Extração de IP do cliente

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

Sinalização 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

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"

Suporte TLS

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

Sinalização 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_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_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=3153600; includeSubdomains;" é adicionado em todas as respostas do back-end local. Não é válido para back-ends remotos.
--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.

Sinalização 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.

Transcodificação do gRPC

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

Sinalização 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_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.

Opções de segurança

Use essas sinalizações para refinar ainda mais as solicitações que o ESPv2 permite.

Sinalização Descrição
--underscores_in_headers

Permite a passagem de nomes de cabeçalho com sublinhados. O padrão é false.

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

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

A seguir

Saiba mais sobre: