O Extensible Service Proxy (ESP) é um proxy baseado em NGINX usado pelo Cloud Endpoints para fornecer recursos de gerenciamento de APIs. Para configurar o ESP, você especifica opções ao iniciar o contêiner do Docker do ESP. Quando o contêiner do ESP é iniciado, ele executa um script chamado start_esp
, que grava o arquivo de configuração NGINX usando as opções especificadas e inicia o ESP.
Especifique as opções de inicialização do ESP no comando docker run
. Por exemplo:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
Se você estiver implantando o ESP no Kubernetes, especifique as opções de inicialização no campo args
do arquivo de manifesto de implantação. Por exemplo:
containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
Veja na tabela a seguir as opções de inicialização do ESP.
Opção curta | Opção longa | Descrição |
---|---|---|
-s SERVICE_NAME |
--service SERVICE_NAME |
Define o nome do serviço do Endpoints. |
-R ROLLOUT_STRATEGY |
--rollout_strategy ROLLOUT_STRATEGY |
Disponível no ESP versão 1.7.0 e superior. Especifique |
-v CONFIG_ID |
--version CONFIG_ID |
Define o ID de configuração do serviço a ser usado pelo ESP. Para mais informações necessárias para definir essa opção, consulte Como conseguir o nome do serviço e o ID de configuração.
Quando você especifica --rollout_strategy=fixed ou quando não inclui a opção --rollout_strategy , é necessário adicionar --version e especificar um ID de configuração. Nesse caso, sempre que você implantar uma nova configuração do Endpoints, será necessário reiniciar o ESP com o novo ID de configuração.
|
-p HTTP1_PORT |
--http_port HTTP1_PORT |
Define as portas que o ESP expõe para conexões HTTP/1.x.1 |
-P HTTP2_PORT |
--http2_port HTTP2_PORT |
Define as portas que o ESP expõe para conexões HTTP/2.1 |
-S SSL_PORT |
--ssl_port SSL_PORT |
Define as portas que o ESP expõe para conexões HTTPS.1 |
-a BACKEND |
--backend BACKEND |
Define o endereço do servidor de back-end do aplicativo HTTP/1.x. O valor padrão do endereço de back-end é http://127.0.0.1:8081 .É possível especificar um prefixo de protocolo. Por exemplo: --backend=https://127.0.0.1:8000 Se você não especificá-lo, o padrão será http .Se o servidor de back-end estiver em execução no Compute Engine em um contêiner, será possível especificar o nome do contêiner e a porta. Por exemplo: --backend=my-api-container:8000 Para especificar que o back-end aceita o tráfego gRPC, adicione o prefixo grpc:// . Por exemplo:--backend=grpc://127.0.0.1:8000 Se o servidor de back-end estiver em execução no Compute Engine em um contêiner e aceitar o tráfego gRPC, será possível especificar o nome do contêiner e a porta. Por exemplo: --backend=grpc://my-api-container:8000
|
-N STATUS_PORT |
--status_port STATUS_PORT |
Define a porta de status. O padrão é 8090 . |
nenhuma | --disable_cloud_trace_auto_sampling |
Por padrão, o ESP toma 1 amostra de solicitação a cada 1.000 ou 1 solicitação a cada 10 segundos é ativada com o Cloud Trace. Defina essa sinalização para desativar a amostragem automática. O Cloud Trace ainda pode ser ativado a partir de cabeçalhos HTTP de solicitação com contexto de rastreamento, independentemente desse valor de sinalização. Consulte Como rastrear a API para mais informações. |
-n NGINX_CONFIG |
--nginx_config NGINX_CONFIG |
Define o local do arquivo de configuração personalizado do NGINX. Se você especificar essa opção, o arquivo de configuração determinado será buscado pelo ESP, e o NGINX será inicializado com o arquivo de configuração personalizado fornecido. Para mais informações, consulte Como usar uma configuração nginx personalizada no GKE. |
-k SERVICE_ACCOUNT_KEY |
--service_account_key SERVICE_ACCOUNT_KEY |
Define o arquivo JSON das credenciais da conta de serviço. Se fornecido, o ESP usa a conta de serviço para gerar um token de acesso e chamar as APIs da infraestrutura de serviços. O único momento em que você precisa especificar essa opção é quando o ESP está sendo executado em plataformas diferentes do Google Cloud, como sua área de trabalho local, o Kubernetes ou outro provedor de nuvem. Para mais informações, consulte Como criar uma conta de serviço. |
-z HEALTHZ_PATH |
--healthz HEALTHZ_PATH |
Define um endpoint de verificação de integridade nas mesmas portas que o back-end do aplicativo. Por exemplo, -z healthz faz o ESP retornar o código 200 para o local /healthz , em vez de encaminhar a solicitação ao back-end. Padrão: não usado.
|
nenhuma | --dns DNS_RESOLVER |
Especifique um resolvedor de DNS. Por exemplo, --dns 169.254.169.254 usa o servidor de metadados do GCP como o resolvedor de DNS. Caso não seja especificado, o padrão será 8.8.8.8 .
|
1 Essas portas são opcionais e precisam ser diferentes umas das outras.
Se você não especificar opções de porta, o ESP aceitará as conexões HTTP/1.x na porta 8080
.
No caso das conexões HTTPS, os secrets TLS são buscados pelo ESP em /etc/nginx/ssl/nginx.crt
e /etc/nginx/ssl/nginx.key
.
Exemplos de invocações da linha de comando
Veja nos exemplos a seguir como usar alguns dos argumentos da linha de comando:
Para iniciar o ESP de modo que ele processe solicitações recebidas nas portas HTTP/1.x 80
e HTTPS 443
e envie as solicitações ao back-end da API em 127.0.0.1:8000
, execute:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --http_port=80 \ --ssl_port=443 \ --backend=127.0.0.1:8000
Se quiser iniciar o ESP com uma configuração do NGINX personalizada usando o arquivo de credenciais da conta de serviço para buscar a configuração do serviço e conectar-se ao controle de serviço, execute:
sudo docker run \ --detach \ --volume=$HOME/Downloads:/esp \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --service_account_key=/esp/serviceaccount.json \ --nginx_config=/esp/nginx.conf
Use as sinalizações do Docker --volume
ou --mount
para ativar o arquivo JSON com a chave privada da conta de serviço e o arquivo de configuração personalizado do NGINX como volumes dentro do contêiner do Docker do ESP. O exemplo anterior mapeia o diretório $HOME/Downloads
no computador local para o diretório esp
no contêiner. Quando você salva o arquivo de chave privada da conta de serviço, geralmente o download dele é feito para o diretório Downloads
. É possível copiá-lo para outro diretório, se você quiser. Consulte
Gerenciar dados no Docker
para mais informações.
Como adicionar suporte CORS ao ESP
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 ESP para oferecer suporte ao CORS.
Para ativar o suporte ao CORS no ESP, inclua a opção --cors_preset
e a defina como basic
ou cors_with_regex
. Quando você inclui --cors_preset=basic
ou --cors_preset=cors_with_regex
, o ESP:
- 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_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
A expressão regular no exemplo anterior possibilita uma origem com |
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_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_credentials |
Inclui o cabeçalho Access-Control-Allow-Credentials 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_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
|
Se as opções de inicialização do CORS do ESP não atenderem às necessidades do aplicativo, crie um arquivo nginx.conf
personalizado com o suporte ao CORS necessário para o aplicativo. Para mais informações, consulte Como criar um nginx.conf
personalizado para aceitar o CORS.
A seguir
Saiba mais sobre:
- Como implantar o ESP e o back-end de API no Google Cloud
- Como executar o ESP localmente ou em outra plataforma
- Script
start_esp
(em inglês) no GitHub