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

O Extensible Service Proxy (ESP) é um proxy baseado em NGINX que permite que o Cloud Endpoints forneça recursos de gerenciamento de APIs. Configure o ESP especificando opções personalizadas ao iniciar o contêiner do Docker ESP. Quando o contêiner 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 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 a descrição das opções de inicialização do ESP na tabela a seguir.

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 posterior. Especifique managed ou fixed. Com a opção --rollout_strategy=managed, o ESP é configurado para usar a implantação mais recente da configuração de serviço. Quando essa opção é especificada, a alteração é detectada pelo ESP até um minuto após a implantação de uma nova configuração de serviço e começa a ser usada automaticamente. Recomendamos especificar esta opção em vez de um código de configuração específico para uso do ESP. Você não precisa especificar a opção --version quando define --rollout_strategy como managed.

-v CONFIG_ID --version CONFIG_ID Define o código de configuração do serviço a ser usado pelo ESP. Consulte Como conseguir o nome e o código de configuração do serviço para mais informações sobre como configurar esta opção. Quando você especifica --rollout_strategy=fixed ou não inclui a opção --rollout_strategy, é preciso incluir --version e especificar um código de configuração. Nesse caso, sempre que implantar uma nova configuração do Endpoints, você precisará reiniciar o ESP com o novo código 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.
Especifique um prefixo de protocolo, por exemplo:
--backend=https://127.0.0.1:8000
Se você não especificar um prefixo de protocolo, 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 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 do 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_trace_sampling Por padrão, o ESP faz a amostragem de um pequeno número de solicitações à API a cada segundo para ver os traces enviados ao Stackdriver Trace. Defina esta opção booleana como true para desativar a amostragem de trace. 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 esta opção, o arquivo de configuração especificado será buscado pelo ESP e, em seguida, o NGINX será inicializado com o arquivo de configuração personalizado.
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY Define o arquivo JSON das credenciais da conta de serviço. Se essa conta for informada, o ESP a usará para gerar um token de acesso para chamar as APIs Service Infrastructure. A única vez que você precisa especificar esta opção é quando o ESP é executado em outras plataformas que não o Google Cloud Platform (GCP), como seu desktop 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 gera o código de retorno 200 no ESP para o local /healthz em vez de encaminhar a solicitação para o back-end. O padrão não é usado.

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

Os exemplos a seguir mostram como usar alguns dos argumentos da linha de comando:

Para iniciar o ESP de modo que ele processe solicitações recebidas na porta HTTP/1.x 80 e na porta HTTPS 443 e envie as solicitações para o back-end da API em 127.0.0.1:8000, use este comando:

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

Para 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, use este comando:

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 do NGINX personalizada como volumes dentro do contêiner do Docker do ESP. O exemplo acima mapeia o diretório $HOME/Downloads no computador local para o diretório esp no contêiner. Quando você salva o arquivo da chave privada na conta de serviço, o download geralmente é feito no diretório Downloads. É possível copiar o arquivo da chave privada em outro diretório. Consulte Gerenciar dados no Docker (em inglês) para mais informações.

Como adicionar suporte CORS ao ESP

O compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que chamadas XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de origens diferentes. Sem o CORS, a política de mesma origem que é aplicada por todos os navegadores impede solicitações de origem cruzada. Para mais informações de referência sobre o CORS, consulte a documentação da Web do Mozilla Developer Network (MDN) (em inglês).

Para ativar o suporte ao CORS no ESP, inclua a opção --cors_preset e defina-a 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 tenham a mesma política de CORS;
  • responde a solicitações simples e de simulação de HTTP OPTIONS;
  • 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 modificar o valor padrão de Access-Control-Allow-Origin, especifique uma das opções a seguir:

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. Isso 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 a opção em um arquivo de configuração do Kubernetes, é preciso adicionar um caractere de barra invertida adicional para escapar de ambas as instâncias de \. na string, por exemplo:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

Depois de definir --cors_preset=basic ou --cors_preset=cors_with_regex para ativar o CORS, é possível substituir os valores padrão dos outros cabeçalhos de resposta, especificando 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 está incluído nas respostas.
Exemplo:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Define Access-Control-Expose-Headers como 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, será possível criar um arquivo nginx.conf personalizado com o suporte ao CORS que o aplicativo requer. Para mais informações, consulte Como criar um nginx.conf personalizado compatível com CORS.

A seguir

Saiba mais sobre:

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.