Esta página foi traduzida pela API Cloud Translation.

Como executar o Extensible Service Proxy no local 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ê vai aprender a 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: é preciso que esse projeto seja o mesmo 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 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.
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 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:

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 CLI do Google Cloud (gcloud) está autorizada a acessar 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 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?

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

Nos exemplos a seguir, a opção --http_port do ESP funcionará somente se o serviço gRPC tiver transcodificação HTTP/JSON configurada. Para mais informações, consulte Como transcodificar HTTP/JSON para gRPC.

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 \
    --http2_port=8083 \
    --backend=grpc://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 \
  --http2_port=8083 \
  --backend=grpc://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 \
  --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.

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`	No macOS, quando você quiser executar o ESP no local, use esta opção do Docker em vez de `--net="host"` para fazer o mapeamento explícito de portas do host no 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",
          "--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.

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

Como fazer a limpeza

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, consulte Como excluir uma API e as instâncias relacionadas.

A seguir

Saiba como adicionar suporte SSL ao ESP