Este tutorial mostra como implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy V2 (ESPv2) em um contêiner do Docker no Compute Engine.
Este tutorial 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.
- Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
- Crie uma instância de VM do Compute Engine. Consulte Como criar uma instância do Compute Engine.
- Copie e configure arquivos da amostra
bookstore-grpc
. Consulte Como configurar o Endpoints. - Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
- Implante a API e o ESPv2 na VM do Compute Engine. Consulte Como implantar o back-end da API.
- Envie uma solicitação à API. Consulte Como enviar uma solicitação à API.
- Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em 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.
-
Make sure 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.
-
Make sure that billing is enabled for your Google Cloud project.
- Anote o código do projeto, ele será necessário mais tarde.
- Instale e inicialize a Google Cloud CLI.
- Atualize a CLI gcloud e instale os componentes do Endpoints:
gcloud components update
-
Verifique se a Google Cloud CLI (
gcloud
) está autorizada a acessar seus dados e serviços no Google Cloud: Na nova guia aberta no navegador, selecione uma conta.gcloud auth login
- 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ê tem outros projetos do Google Cloud e quer usar
gcloud
para gerenciá-los, consulte Como CLI gcloud gcloud. - 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.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Como criar uma instância do Compute Engine
Para criar uma instância do Compute Engine:
- In the Google Cloud console, go to the Create an instance page.
- Na seção Firewall, selecione Permitir tráfego HTTP e Permitir tráfego HTTPS.
- Para criar a VM, clique em Criar.
- Verifique se você consegue se conectar à instância da VM.
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
- Agora é possível usar o terminal para executar comandos do Linux na instância do Debian.
- Digite
exit
para se desconectar da instância.
- Anote o nome, a zona e o endereço IP externo da instância. Eles serão necessários mais tarde.
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.
Como configurar o Endpoints
Clone o repositório de amostra bookstore-grpc
do GitHub.
Para configurar o Endpoints:
- Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço
.proto
:- Salve uma cópia de
bookstore.proto
do repositório de exemplo. Esse arquivo define a API do serviço Bookstore. - Crie o seguinte diretório:
mkdir generated_pb2
- Crie o arquivo de descritor,
api_descriptor.pb
, usando o compilador de buffers de protocoloprotoc
. Execute o seguinte comando no diretório onde você salvoubookstore.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
No comando anterior,
--proto_path
está definido como o diretório de trabalho atual. No ambiente da versão do gRPC, caso você use um diretório diferente para arquivos de entrada.proto
, mude--proto_path
para que o compilador pesquise o diretório em que salvoubookstore.proto
.
- Salve uma cópia de
- Crie um arquivo YAML de configuração da API gRPC:
- Salve uma cópia do arquivo
api_config.yaml
. Esse arquivo define a configuração da API gRPC do serviço Bookstore. - Substitua MY_PROJECT_ID no arquivo
api_config.yaml
pelo ID do projeto do Google Cloud. Exemplo:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
Observe que o valor do campo
apis.name
neste arquivo corresponde exatamente ao nome da API totalmente qualificado do arquivo.proto
; caso contrário, a implantação não funcionará. O serviço Bookstore é definido embookstore.proto
dentro do pacoteendpoints.examples.bookstore
. O nome da API totalmente qualificado éendpoints.examples.bookstore.Bookstore
, assim como aparece no arquivoapi_config.yaml
.apis: - name: endpoints.examples.bookstore.Bookstore
- Salve uma cópia do arquivo
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.
- Verifique se você está no diretório onde os arquivos
api_descriptor.pb
eapi_config.yaml
estão localizados. - Confirme se o projeto padrão que a ferramenta de linha de comando
gcloud
está usando no momento é o projeto do Google Cloud em que você pretende implantar a configuração do Endpoints. Valide o código do projeto retornado do comando a seguir para garantir que o serviço não seja criado no projeto incorreto.gcloud config list project
Se você precisar alterar o projeto padrão, execute o comando:
gcloud config set project YOUR_PROJECT_ID
- Implante o arquivo
proto descriptor
e o arquivo de configuração usando o Google Cloud CLI:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a implantação for concluída, uma mensagem parecida com esta será exibida:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID é o ID exclusivo de configuração de serviço do Endpoints criado pela implantação. Exemplo:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
No exemplo anterior,
2017-02-13r0
é o ID de configuração do serviço ebookstore.endpoints.example-project.cloud.goog
é o nome do serviço. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar novamente a configuração do Endpoints no mesmo dia, o número de revisão será alterado no código da configuração do serviço.
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 do Google Cloud existente, em que esses serviços foram desativados explicitamente.
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:
Após implantar a configuração de 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 camponame
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 ESPv2 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:
- 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.
- Conecte-se à instância usando o seguinte comando:
gcloud compute ssh INSTANCE_NAME
Substitua INSTANCE_NAME pelo nome da instância de VM.
- 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
Execute a API de amostra e o ESPv2 em um contêiner do Docker
Para executar o serviço gRPC de exemplo com o ESPv2 em um contêiner Docker para que os clientes possam usá-lo, faça o seguinte:
- Na instância da VM, crie sua própria rede de contêiner chamada
esp_net
.sudo docker network create --driver bridge esp_net
- 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
- Execute o contêiner predefinido do Docker ESPv2. Nas
opções de inicialização do ESPv2, substitua
SERVICE_NAME pelo nome do serviço. Esse é o mesmo nome configurado no campo
name
do arquivoapi_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:2 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --listener_port=9000 \ --backend=grpc://bookstore:8000
A opção
--rollout_strategy=managed
configura o ESPv2 para usar a implantação mais recente da configuração do serviço. Ao especificar essa opção, a alteração é detectada pelo ESPv2 em até um minuto após a implantação de uma nova configuração do serviço e começa a ser usada automaticamente. Recomendamos especificar essa opção em vez de fornecer um ID de configuração específico para o ESPv2. Para mais detalhes sobre os argumentos do ESPv2, consulte Opções de inicialização do ESPv2.
Caso você receba uma mensagem de erro, consulte Como solucionar problemas do Endpoints no Compute Engine.
Como enviar uma solicitação à API
Se você estiver enviando a solicitação da mesma instância em que os contêineres do Docker
estão em execução, 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
Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.
Clone o repositório do Git onde o código do cliente gRPC está hospedado:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Altere o diretório de trabalho:
cd python-docs-samples/endpoints/bookstore-grpc/
Instale as dependências:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
Envie uma solicitação à API de amostra:
python bookstore_client.py --host SERVER_IP --port 80
Veja os gráficos de atividade da API na página Endpoints > Serviços.
Ir para a página Serviços do Endpoints
Pode levar alguns instantes até a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Explorador de registros".
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.
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.
- Exclua a API:
gcloud endpoints services delete SERVICE_NAME
Substitua
SERVICE_NAME
pelo nome do serviço. - In the Google Cloud console, go to the VM instances page.
- Select the checkbox for the instance that you want to delete.
- 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 Java (links em inglês).
- A amostra
getting-started-grpc
está disponível no GitHub nas seguintes linguagens: