Como executar o ESP localmente ou em outra plataforma

OpenAPI | gRPC

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

Nesta seção, você verá instruções sobre como configurar e implantar localmente a versão em Python da amostra getting-started para Endpoints. 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:

Acessar o exemplo de código

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

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

Acesse o diretório que contém o código de amostra:
```
cd python-docs-samples/endpoints/getting-started
```

Configurar o Endpoints

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"

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

Importante :precisa ser o mesmo projeto selecionado em Como criar a conta de serviço.
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.

Atualizar a CLI gcloud:
```
gcloud components update
```
Verifique se a CLI gcloud (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.
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.

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

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

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

Inicie o servidor:
```
python main.py
```

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, o Compute Engine ou o ambiente flexível do App Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.

Ao implantar o ESP ou ESPv2 em um ambiente que não seja do Google Cloud, como seu computador local, um cluster do Kubernetes local ou outro provedor de nuvem, é preciso fornecer 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 a API.

É possível usar o console do Google Cloud ou a Google Cloud CLI para criar a conta de serviço e o arquivo de chave privada:

Console

No console do Google Cloud, abra a página Contas de serviço .
Acesse a página Contas de serviço
Clique em Selecione um projeto.
Selecione o projeto em que a API foi criada e clique em Abrir.
Clique em + Criar conta de serviço.
No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
Clique em Criar.
Clique em Continuar.
Clique em Concluído.
Clique no endereço de e-mail da conta de serviço recém-criada.
Clique em Chaves.
Clique em Adicionar chave e em Criar nova chave.
Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.

Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. Mova e renomeie esse arquivo como quiser.
Clique em Fechar.

`gcloud`

Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:
```
gcloud projects list
```
Substitua PROJECT_ID no comando a seguir para definir o projeto que contém sua API como padrão:
```
gcloud config set project PROJECT_ID
```
Importante: é preciso criar a conta de serviço no mesmo projeto em que está a API.
Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud:
```
gcloud auth login
```
Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud e que contém a API. Se você executar gcloud auth list, a conta selecionada será mostrada como a ativa para o projeto.
Para criar uma conta de serviço, execute o seguinte comando e substitua SERVICE_ACCOUNT_NAME e My Service Account pelo nome e pelo nome de exibição que você quer usar:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Esse endereço de e-mail é necessário nos comandos subsequentes.

Crie um arquivo da chave da conta de serviço:

gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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 mais informações, consulte O que são funções e permissões?

Para mais informações sobre os comandos, consulte gcloud iam service-accounts.

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

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.
No comando docker run a seguir, substitua YOUR_SERVICE_NAME pelo nome do seu serviço.

Linux

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 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

macOS

A opção --net="host" do Docker não funciona no macOS. Em vez disso, é preciso fazer o mapeamento explícito de portas do host no contêiner substituindo --net="host" por --publish 8082:8082. Também é necessário substituir localhost pelo nome de DNS especial, somente para macOS, docker.for.mac.localhost. Para mais informações, consulte Casos de uso e soluções alternativas (em inglês) na documentação do Docker.

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 \
  --backend=docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

Outra plataforma

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 \
  --backend=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.

Opção	Descrição
`--detach`	Esta opção do Docker inicia o contêiner no modo independente, portanto ele é executado em segundo plano.
`--name="esp"`	Esta opção do Docker fornece um nome fácil de acessar para o contêiner. Por exemplo, para ver os registros do contêiner, execute `docker logs esp`.
`--net="host"`	Esta opção do Docker indica que o contêiner usa a mesma configuração de rede que a máquina host, permitindo que ele faça chamadas para o localhost na máquina host. Ela não funciona para executar o ESP localmente no macOS.
`--publish=8082:8082`	Para macOS, quando você quiser executar o ESP localmente, use esta opção do Docker em vez de `--net="host"` para fazer o mapeamento explícito de portas do host para o contêiner.
`--volume=` `$HOME/Downloads:/esp`	Essa opção do Docker mapeia seu diretório `$HOME/Downloads` local no diretório `/esp` no contêiner. Esse mapeamento é usado pela opção do ESP `--service_account_key`.

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.

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.
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.

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",
          "--backend=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.

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:

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

Acessar a página Credenciais
Clique em Criar credenciais e selecione Chave de API.
Copie e cole a chave na seguinte instrução de variável de ambiente:
```
export KEY=AIza...
```

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"
}

Limpar

Encerre e remova o Docker esp usando a ferramenta docker:

    sudo docker stop esp
    sudo docker rm esp

Para limpar a configuração do serviço implantado, veja Como excluir uma API e as instâncias relacionadas.

A seguir

Saiba como adicionar suporte SSL ao ESP