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

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 managed ou fixed. A opção --rollout_strategy=managed configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP. Não é preciso especificar a opção --version ao definir --rollout_strategy como managed.
-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 (padrão: 8090).
nenhum --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 (em inglês) 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=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 possibilita uma origem com http ou https e qualquer subdomínio de example.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_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 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

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: