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ê já fez o seguinte:

  • Instalou o Docker, se estiver implantando o contêiner do ESP localmente ou em uma VM. Para mais informações, consulte Instalar Docker (em inglês).

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

Conseguir 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:

Receba o código de amostra

  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. Atualize o SDK do Cloud:

    gcloud components update
    
  2. Verifique se o SDK do Cloud (gcloud) está autorizado 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 o gerenciamento da API, o ESP precisa dos serviços da Infraestrutura de serviços. Para chamá-los, o ESP precisa usar tokens de acesso. Quando você implanta o ESP em ambientes do Google Cloud, como o GKE, o Compute Engine ou o ambiente flexível do App Engine, o ESP recebe tokens de acesso para você por meio do serviço de metadados do Google Cloud.

Quando você implanta o ESP em um ambiente que não é do Google Cloud, como sua área de trabalho 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 ao ESP. O ESP usa a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.

Você pode usar o Console do Cloud ou a ferramenta de linha de comando gcloud para criar a conta de serviço e o arquivo de chave privada e atribuir as funções abaixo a essa conta:

Console

  1. No Console do 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 Selecionar um papel e selecione Gerenciamento de serviços > Controlador de serviços.
  8. Clique em + Adicionar outro papel.
  9. Clique em Selecionar um papel e selecione Cloud Trace > Agente do Cloud Trace.
  10. Clique em Continuar.
  11. Clique em + Criar chave.
  12. No painel do lado direito, para o Tipo de chave, use o tipo padrão, JSON.
  13. Clique em Criar.
  14. Na caixa de diálogo, clique em Fechar.
  15. Clique em Concluído.

Esse procedimento cria a conta de serviço e faz o download da chave privada dela como um arquivo JSON.

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 o SDK do Cloud (gcloud) está autorizado a acessar dados e serviços no Google Cloud:

    gcloud auth login
    

    Se você tiver mais de uma conta, escolha a conta que está no projeto do Google Cloud em que a API está localizada. 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
    
  6. Adicione o papel de Controlador de serviço:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/servicemanagement.serviceController
    
  7. Adicione o papel de Agente do Cloud Trace para ativar o Cloud Trace:

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

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 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 (em inglês) 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. Por exemplo:

Solicitação:

    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. Por exemplo:

Solicitação:

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

A seguir