Como executar o ESP localmente 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ê:

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:

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, 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 o ESPv2 em um ambiente que não seja do Google Cloud, como seu computador local, um cluster do Kubernetes local ou outro provedor em nuvem, é preciso fornecer um arquivo JSON da conta de serviço que contenha 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.

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

Console

  1. No console do Google Cloud, abra a página Contas de serviço .

    Acesse a página Contas de serviço

  2. Clique em Selecione um projeto.
  3. Selecione o projeto em que a API foi criada e clique em Abrir.
  4. Clique em + Criar conta de serviço.
  5. No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
  6. Clique em Criar
  7. Clique em Continuar.
  8. Clique em Concluído.
  9. Clique no endereço de e-mail da conta de serviço recém-criada.
  10. Clique em Chaves.
  11. Clique em Adicionar chave e em Criar nova chave.
  12. 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.

  13. Clique em Fechar.

gcloud

  1. Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:

    gcloud projects list
  2. 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
  3. Verifique se a Google Cloud CLI (gcloud) tem autorização para acessar seus 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.

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

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

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

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

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

  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
Para limpar a configuração do serviço implantado, consulte Como excluir uma API e as instâncias relacionadas.

A seguir