Como executar o Extensible Service Proxy no local ou em outra plataforma

Nesta página, você aprende a configurar e executar uma instância do Extensible Service Proxy (ESP) em um computador local, em outro provedor de nuvem como a Amazon Web Services (AWS) ou em um cluster do Kubernetes que não esteja no Google Cloud.

É possível executar o ESP em uma máquina virtual (VM, na sigla em inglês) ou computador Linux ou macOS. O Microsoft Windows não é compatível. É possível implantar o aplicativo e o ESP no mesmo host ou em hosts diferentes. Hospedar uma instância local do ESP permite que você:

• teste o ESP antes de implantá-lo em uma plataforma de produção;
• verifique se as definições de segurança estão configuradas e funcionando corretamente e se as métricas e os registros aparecem na página Endpoints > Serviços conforme o esperado.

Pré-requisitos

Como ponto de partida nesta página, presume-se que você:

• Instalou o Docker, se estiver implantando o contêiner do ESP localmente ou em uma VM. Consulte Instalar o Docker para mais informações.

• Implantou uma API localmente ou em um host acessível ao host em que o ESP será executado.

• Configurou o Cloud Endpoints e implantou a configuração para criar um serviço gerenciado para a API.

Se precisar de uma API para testar com o ESP, configure e implante o código de amostra na seção Opcional: como usar uma API de amostra. Se você já configurou e implantou a API, pule para Como criar uma conta de serviço.

Opcional: como usar uma API de amostra

Esta seção mostra como configurar e implantar a versão Python do as getting-started para Endpoints uma amostra local. Siga as etapas desta seção somente se não tiver uma API para testar com o ESP.

A amostra getting-started do Cloud Endpoints está disponível em outras linguagens. Para localizar getting-started na linguagem de sua escolha no GitHub, consulte a página "Amostras". Siga as instruções apresentadas no arquivo README.md da amostra para execução local e siga as instruções nesta seção para configurar e implantar a definição do Endpoints.

Consiga o software necessário

Se você ainda não configurou o ambiente de desenvolvimento Python, veja instruções em Como configurar um ambiente de desenvolvimento Python. Veja se você tem os itens a seguir instalados:

• virtualenv
• A CLI do Google Cloud
• curl

Acessar o exemplo de código

1. Clone o repositório do app de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. Acesse o diretório que contém o código de amostra:

   cd python-docs-samples/endpoints/getting-started
   

Configurar o Endpoints

1. No diretório de código de amostra, abra o arquivo de configuração openapi.yaml.

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

2. No campo host, substitua YOUR-PROJECT-ID pelo próprio ID do projeto do Google Cloud.

3. Salve o arquivo openapi.yaml.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

1. Atualizar a CLI gcloud:

   gcloud components update

2. Verifique se a gcloud CLI (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud:

   gcloud auth login

   Na nova guia aberta no navegador, selecione uma conta.

3. Defina o projeto padrão como o ID do projeto:

   gcloud config set project YOUR-PROJECT-ID
   

   Substitua YOUR-PROJECT-ID pelo ID do projeto do Google Cloud que você especificou no arquivo openapi.yaml.

4. Implante a configuração:

   gcloud endpoints services deploy openapi.yaml

O Service Management usa o texto que você especificou no campo host do arquivo openapi.yaml para criar um novo serviço do Endpoints com o nome echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog, se ele não existir, e configura o serviço de acordo com o arquivo de configuração OpenAPI.

Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos no arquivo openapi.yaml que não exigem uma chave de API. Após a conclusão, será exibida uma linha, conforme mostrado a seguir, com o ID de configuração e o nome do serviço entre colchetes:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o nome do serviço.

Como iniciar o servidor local

1. Crie um virtualenv, ative-o e instale as dependências do aplicativo.

   virtualenv env
   source env/bin/activate
   pip install -r requirements.txt

2. Inicie o servidor:

   python main.py
   

3. Abra outra janela de terminal e use curl para enviar uma solicitação:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8080/echo
   

   A mensagem enviada é retornada pela API com a seguinte resposta:

   {
   "message": "hello world"
   }

Como criar uma conta de serviço

Para fornecer gerenciamento da API, o ESP e o ESPv2 exigem os serviços do Service Infrastructure. Para chamá-los, o ESP e o ESPv2 precisam usar tokens de acesso. Quando você implanta o ESP ou o ESPv2 nos ambientes do Google Cloud, como o GKE ou o Compute Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.

Quando você implanta o ESP ou ESPv2 em um ambiente que não é do Google Cloud, como como sua área de trabalho local, um cluster do Kubernetes no local ou outra nuvem provedor, forneça um arquivo JSON da conta de serviço que contém uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar sua API.

Use o console ou a Google Cloud CLI para criar a conta de serviço e o arquivo de chave privada:

Adicione os papéis necessários do IAM:

Nesta seção, descrevemos os recursos do IAM que o ESP e o ESPv2 usam, além dos papéis do IAM necessários para que a conta de serviço anexada acesse esses recursos.

Configuração do serviço de endpoint

O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço do endpoint. A configuração do serviço do endpoint é um recurso do IAM, e o ESP e o ESPv2 precisam do papel Controlador de serviço para acessá-lo.

O papel do IAM está na configuração do serviço do endpoint, não no projeto. Os projetos podem ter várias configurações de serviço de endpoint.

Use o comando gcloud a seguir para adicionar o papel à conta de serviço anexada na configuração do serviço do endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Em que
* SERVICE_NAME é o nome do serviço do endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada.

Cloud Trace

O ESP e o ESPv2 chamam o serviço Cloud Trace para exportar o Trace para um projeto. Esse projeto é chamado de projeto de rastreamento. No ESP, o projeto de rastreamento e o projeto que tem a configuração do serviço de endpoint são os mesmos. No ESPv2, o projeto de rastreamento pode ser especificado pela sinalização --tracing_project_id e assume como padrão o projeto de implantação.

O ESP e o ESPv2 exigem o papel Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar o papel à conta de serviço anexada:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Em que
* TRACING_PROJECT_ID é o ID do projeto de rastreamento
. * SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID,iam.gserviceaccount.com é a conta de serviço anexada. Para obter mais informações, consulte O que são papéis e permissões?

Consulte gcloud iam service-accounts para mais informações sobre os comandos.

Como executar o ESP em um contêiner

Nesta seção, descrevemos como implantar o contêiner do ESP. O procedimento usado depende de onde você implantará o contêiner do ESP:

• Como executar o ESP localmente em um contêiner do Docker ou em outra plataforma
• Como executar o ESP no contêiner em um cluster do Kubernetes

Como executar o ESP no local em um contêiner do Docker ou em outra plataforma

1. Renomeie o arquivo JSON que contém a chave privada da conta de serviço como service-account-creds.json e copie-o para $HOME/Downloads/ se ele tiver sido salvo em um diretório diferente. Dessa forma, o nome do caminho completo corresponde ao valor de --service_account_key no seguinte comando docker run.

2. No comando docker run a seguir, substitua YOUR_SERVICE_NAME pelo nome do seu serviço.

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json
  

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json
  

Na tabela a seguir, são descritas as opções do Docker usadas nos comandos acima. Para informações sobre as opções de ESP usadas no exemplo, consulte Opções de inicialização do ESP.

Executar o ESP no contêiner em um cluster do Kubernetes

Nesta seção, você aprende a implantar o ESP em um cluster do Kubernetes que não está no Google Cloud.

Para ter a API gerenciada pelo Endpoints, implante o contêiner ESP no mesmo pod do Kubernetes que o contêiner de API. O conjunto de pods que executam o ESP e sua API são agrupados em um serviço do Kubernetes (em inglês) por meio de um seletor de rótulos, como app: my-api. Esse serviço especifica a política de acesso para balancear a carga de solicitações do cliente na porta do proxy.

1. Renomeie o arquivo JSON que contém a chave privada da conta de serviço como service-account-creds.json e copie-o para $HOME/Downloads/ se ele tiver sido salvo em um diretório diferente. Dessa forma, o nome do caminho completo corresponde ao comando na próxima etapa.

2. Execute o seguinte comando para criar um secret do Kubernetes e ativá-lo como um volume do Kubernetes (ambos em inglês).

   kubectl create secret generic service-account-creds \
     --from-file=$HOME/Downloads/service-account-creds.json
   

   Se o processo for bem-sucedido, a seguinte mensagem será exibida: secret "service-account-creds" created.

3. No arquivo de configuração do Kubernetes, adicione o seguinte, substituindo YOUR_APP_NAME pelo nome da API e YOUR_SERVICE_NAME pelo nome do serviço.

   spec:
   replicas: 1
   template:
     metadata:
       labels:
         app: "YOUR_APP_NAME"
     spec:
       volumes:
         - name: service-account-creds
           secret:
             secretName: service-account-creds
             containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:1
           args: [
             "--http_port=8082",
             "--http2_port=8083",
             "--backend=grpc://127.0.0.1:8081",
             "--service=YOUR_SERVICE_NAME",
             "--rollout_strategy=managed",
             "--service_account_key=/etc/nginx/creds/service-account-creds.json"
           ]
           ports:
             - containerPort: 8080
           volumeMounts:
             - mountPath: /etc/nginx/creds
               name: service-account-creds
               readOnly: true
   

   Para informações sobre as opções de ESP usadas no exemplo, consulte Opções de inicialização do ESP.

4. Implemente o ESP em Kubernetes. Substitua YOUR_CONFIGURATION_FILE pelo nome do arquivo de configuração do Kubernetes.

   kubectl apply -f YOUR_CONFIGURATION_FILE

Como enviar solicitações

Para confirmar que o arquivo da conta de serviço está correto e que as portas estão mapeadas adequadamente, envie algumas solicitações à API e verifique se elas estão passando pelo ESP. É possível ver os registros do ESP executando este comando:

sudo docker logs esp

Os exemplos a seguir enviam solicitações à API de amostra. Se você não a utiliza, execute testes semelhantes.

Você configurou o contêiner do ESP para receber solicitações na porta 8082. Se você enviar uma solicitação diretamente ao servidor em http://localhost:8080, as solicitações ignorarão o ESP. Exemplo:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

Resposta:

  {
    "message": "hello world"
  }

Quando você envia uma solicitação para http://localhost:8082, que passa pelo ESP, sem uma chave de API, o ESP a rejeita. Exemplo:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

Resposta:

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

Para testar a API com uma chave de API:

1. Crie uma chave de API na página de credenciais da API.
   

   Acessar a página Credenciais

2. Clique em Criar credenciais e selecione Chave de API.

3. Copie e cole a chave na seguinte instrução de variável de ambiente:

   export KEY=AIza...
   

4. Envie uma solicitação com a chave:

   curl --request POST \
     --header "content-type:application/json" \
     --data '{"message":"hello world"}' \
     http://localhost:8082/echo?key=$KEY

   Será exibida uma resposta informando que o processo foi bem-sucedido:

   {
     "message": "hello world"
   }

Como fazer a limpeza

Encerre e remova o Docker esp usando a ferramenta docker:

    sudo docker stop esp
    sudo docker rm esp

A seguir

• Saiba como adicionar suporte SSL ao ESP