Primeiros passos com o Endpoints para Compute Engine com ESP

OpenAPI   |  gRPC

Nesta página, você aprende a implantar um exemplo de gRPC simples com o Extensible Service Proxy (ESP) em um contêiner do Docker no Compute Engine.

Esta página usa a versão Python da amostra bookstore-grpc. Consulte a seção A seguir para acessar as amostras do gRPC em outras linguagens.

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.

1. Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
2. Crie uma instância de VM do Compute Engine. Consulte Como criar uma instância do Compute Engine.
3. Copie e configure arquivos da amostra bookstore-grpc. Consulte Como configurar o Endpoints.
4. Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
5. Implantar a API e o ESP na VM do Compute Engine. Consulte Como implantar o back-end da API.
6. Envie uma solicitação para a API. Consulte Como enviar uma solicitação à API.
7. Para evitar cobranças na sua conta do Google Cloud . Consulte Limpeza.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Compute Engine
• Endpoints

Para gerar uma estimativa de custo baseada na sua projeção de uso, utilize a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Anote o código do projeto, ele será necessário mais tarde.
2. Instale e inicialize a Google Cloud CLI.
3. Atualize a CLI gcloud e instale os componentes do Endpoints:

   gcloud components update

4. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços em Google Cloud:

   gcloud auth login

   Na nova guia aberta no navegador, selecione uma conta.
5. Defina o projeto padrão como o ID do projeto.

   gcloud config set project YOUR_PROJECT_ID

   Substitua YOUR_PROJECT_ID pela ID do seu projeto. Se você tiver outros projetos do Google Cloud e quiser usar o gcloud para gerenciá-los, consulte Como gerenciar as configurações da CLI gcloud.

6. Siga as etapas no Guia de início rápido do gRPC para Python (em inglês) para instalar o gRPC e as ferramentas dele.

Como criar uma instância do Compute Engine

Para criar uma instância do Compute Engine:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. Na seção Firewall, selecione Permitir tráfego HTTP e Permitir tráfego HTTPS.
3. Para criar a VM, clique em Criar.



Aguarde até que a instância seja inicializada. Quando estiver pronta, ela aparecerá na página Instâncias de VMs com um ícone de status verde.

4. Verifique se você consegue se conectar à instância da VM.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Agora é possível usar o terminal para executar comandos do Linux na instância do Debian.
   3. Digite exit para se desconectar da instância.
5. Anote o nome, a zona e o endereço IP externo da instância. Eles serão necessários mais tarde.

Como configurar o Endpoints

Clone o repositório bookstore-grpc de amostra do GitHub:

Para configurar o Endpoints:

1. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
   2. Create the following directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved bookstore.proto:

      python -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a gRPC API configuration YAML file:
   1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
   2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.

      apis:
        - name: endpoints.examples.bookstore.Bookstore

Para saber mais, consulte Como configurar o Endpoints.

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. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.

   gcloud config list project
   

   If you need to change the default project, run the following command:

   gcloud config set project YOUR_PROJECT_ID
   

3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

Como verificar os serviços obrigatórios

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:

Nome	Título
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control

Na maioria dos casos, o comando gcloud endpoints services deploy ativa os serviços necessários. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

• Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.

• Você implantou a configuração do Endpoints em um projeto doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

Use o seguinte comando para confirmar se os serviços necessários estão ativados:

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

• Depois de implantar a configuração do Endpoints, acesse a página Endpoints no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

• Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo name da configuração do gRPC Endpoints.

Para mais informações sobre os comandos gcloud, consulte serviços gcloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Para mais informações, consulte Como implantar a configuração do Endpoints.

Como implantar o back-end da API

Até agora, você implantou a configuração da API no Service Management, mas não o código que disponibiliza o back-end da API. Esta seção contém orientações para configurar o Docker na instância de VM e executar o código de back-end da API e o ESP em um contêiner do Docker.

Instalar o Docker na instância de VM

Para instalar o Docker na instância de VM, faça o seguinte:

1. Execute o comando a seguir para definir a zona do projeto:

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Substitua YOUR_INSTANCE_ZONE pela zona em que a instância está em execução.

2. Conecte-se à instância usando o seguinte comando:

   gcloud compute ssh INSTANCE_NAME
   

   Substitua INSTANCE_NAME pelo nome da instância de VM.

3. Consulte a documentação do Docker (em inglês) para configurar o repositório do Docker. Siga os passos que correspondem à versão e à arquitetura da instância da VM:
   • Jessie ou mais recente
   • x86_64/amd64

Executar a API de amostra e o ESP em um contêiner do Docker

Para executar o serviço gRPC de amostra com ESP em um contêiner do Docker para uso dos clientes, faça o seguinte:

1. Na instância da VM, crie sua própria rede de contêiner chamada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Execute o servidor do Bookstore de amostra que fornece a API de amostra:

   sudo docker run \
       --detach \
       --name=bookstore \
       --net=esp_net \
       gcr.io/endpointsv2/python-grpc-bookstore-server:1
   

3. Execute o contêiner predefinido do Docker ESP. Nas opções de inicialização do ESP, substitua SERVICE_NAME pelo nome do serviço. Esse é o mesmo nome configurado no campo name do arquivo api_config.yaml. Por exemplo: bookstore.endpoints.example-project-12345.cloud.goog.

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --http2_port=9000 \
       --backend=grpc://bookstore:8000
   

   A opção --rollout_strategy=managed configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP. Para mais detalhes sobre os argumentos do ESP, consulte Opções de inicialização do ESP.

Se a transcodificação estiver ativada, configure uma porta para HTTP1.1 ou tráfego SSL.

Caso você receba uma mensagem de erro, consulte Como solucionar problemas do Cloud Endpoints no Compute Engine.

Como enviar uma solicitação à API

Caso a solicitação seja enviada a partir da mesma instância em que os contêineres do Docker estão sendo executados, substitua $SERVER_IP por localhost. Caso contrário, substitua $SERVER_IP pelo IP externo da instância.

Para encontrar o endereço IP externo, execute:

gcloud compute instances list

To send requests to the sample API, you can use a sample gRPC client written in Python.

1. Clone the git repo where the gRPC client code is hosted:

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

2. Change your working directory:

   cd python-docs-samples/endpoints/bookstore-grpc/
     

3. Install dependencies:

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

4. Send a request to the sample API:

   python bookstore_client.py --host SERVER_IP --port 80
   

   • Look at the activity graphs for your API in the Endpoints > Services page.
     

     Go to the Endpoints Services page

     It may take a few moments for the request to be reflected in the graphs.

   • Look at the request logs for your API in the Logs Explorer page.
     

     Go to the Logs Explorer page

Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

1. Exclua a API:

   gcloud endpoints services delete SERVICE_NAME

   SERVICE_NAME pelo nome do serviço;

2. In the Google Cloud console, go to the VM instances page.

   Go to VM instances

3. Select the checkbox for the instance that you want to delete.
4. To delete the instance, click More actions, click Delete, and then follow the instructions.

A seguir

• Descubra como configurar sua API gRPC do Cloud Endpoints.
• Consulte a amostra do Bookstore no GitHub para saber mais. Tanto o cliente quanto o servidor estão disponíveis em Python e em Java (links em inglês).
• A amostra getting-started-grpc está disponível no GitHub nas seguintes linguagens:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js