Como executar o Extensible Service Proxy 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 o Amazon Web Services (AWS), ou em um cluster do Kubernetes que não esteja no Google Cloud Platform. (GCP).

É possível executar o ESP em um computador ou uma máquina virtual (VM, na sigla em inglês) 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 configuraçõ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

Nesta seção, veja como configurar e implantar localmente a versão em Python da amostra getting-started para o Endpoints (em inglês). 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 outros idiomas. Para localizar a amostra getting-started do GitHub na linguagem de sua escolha, consulte a página getting-started. Siga as instruções no arquivo README.md da amostra para execução local. Depois disso, siga os passos nesta seção para configurar o Endpoints e implantar a configuração dele.

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 seguintes itens instalados:

Como conseguir 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
    

Configure o Endpoints

  1. No diretório do 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 ID do projeto do GCP.

  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. Esse comando usa 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 GCP:

    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 GCP especificado no arquivo openapi.yaml.

  4. Implante a configuração.

    gcloud endpoints services deploy openapi.yaml
    

O texto especificado no campo host do arquivo openapi.yaml é usado pelo Service Management para criar um novo serviço do Endpoints denominado echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (se ele não existir). Em seguida, o serviço é configurado de acordo com o arquivo de configuração da OpenAPI.

Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. É possível ignorar com tranquilidade os avisos sobre os caminhos no arquivo openapi.yaml que não requerem uma chave de API. Após a conclusão, será exibida uma linha, conforme mostrado a seguir, com o código 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 código 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 do 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"
    }
    

Criar uma conta de serviço

Para o gerenciamento da API, o ESP precisa dos serviços da Service Infrastructure. Para chamá-los, o ESP precisa usar tokens de acesso. Quando implantado nas plataformas do GCP, como o GKE ou o Compute Engine, o ESP recebe tokens de acesso por meio do serviço de metadados do GCP.

Ao implantar o ESP em um ambiente que não seja do GCP, como seu computador local, um cluster do Kubernetes local ou em outro provedor de nuvem, é preciso fornecer ao ESP um arquivo JSON da conta de serviço que contenha uma chave privada. O ESP usa a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.

Use o Console do GCP ou a ferramenta de linha de comando gcloud para criar a conta de serviço e o arquivo de chave privada e para atribuir os seguintes papéis à conta:

Console

  1. No Console do GCP, abra a página Contas de serviço.

    Acessar 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. Para exibir os códigos dos projetos do GCP, digite:

    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 seus dados e serviços no GCP:

    gcloud auth login
    

    Se você tiver mais de uma conta, escolha a conta presente no projeto do GCP em que está 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 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 Stackdriver Trace:

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

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:

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

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

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

  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 \
    --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 para o contêiner, substituindo --net="host" por --publish 8082:8082. Também é necessário substituir localhost pelo nome DNS especial, somente para macOS, docker.for.mac.localhost. Para mais informações, consulte Casos de uso e soluções alternativas 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, É possível executar 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. Esta opção não funciona para executar o ESP localmente no macOS.
--publish=8082:8082 Para o 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
Esta opção do Docker mapeia o diretório local $HOME/Downloads para o /esp no contêiner. Esse mapeamento é usado pela opção do ESP --service_account_key.

Como executar o ESP no contêiner em um cluster do Kubernetes

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

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ótulo, 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 particular para a conta de serviço para service-account-creds.json e copie-o para $HOME/Downloads/ se ele foi baixado para 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 montá-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 comando a seguir, substituindo YOUR_APP_NAME pelo nome da API e YOUR_SERVICE_NAME pelo nome do seu 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 para o 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, ele 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"
    }
    

Limpar

Encerre e remova o contêiner do 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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.