Primeiros passos com o gRPC no Compute Engine

Nesta página, você aprenderá como implantar um exemplo de serviço gRPC simples com o Extensible Service Proxy (ESP) em um contêiner do Docker (em inglês) no Compute Engine.

Esta página usa a versão Python da amostra bookstore-grpc (em inglês). 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. Para enviar solicitações à API, é necessário concluir todas as tarefas.

  1. Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
  2. Criar 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 (em inglês). 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 à API. Consulte Como enviar uma solicitação à API.
  7. Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.

Custos

Neste tutorial, usamos 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. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Anote o ID do projeto. Ele será necessário mais tarde.
  5. Instale e inicialize o Cloud SDK.
  6. Atualize o SDK do Cloud e instale os componentes do Endpoints:
    gcloud components update
  7. 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.
  8. 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. Se você tem outros projetos do Google Cloud e quer usar gcloud para gerenciá-los, consulte Como gerenciar configurações do SDK do Cloud.

  9. 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. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar a página Instâncias de VM (em inglês)

  2. Clique em Criar instância.
  3. Na seção Firewall, selecione Permitir tráfego HTTP e Permitir tráfego HTTPS.
  4. Clique em Criar para criar a instância.
  5. Captura de tela da janela de criação da instância de VM com as opções necessárias definidas

    Aguarde a inicialização da instância. Quando estiver pronta, ela aparecerá na página **Instâncias de VMs** com um ícone de status verde.

  6. Verifique se você consegue se conectar à instância da VM.
    1. Na lista de instâncias de máquina virtual, clique em SSH na linha da instância à qual você quer se conectar.
    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.
  7. Anote o nome, a zona e o endereço IP externo da instância. Eles serão necessários mais tarde.

Configurar o Endpoints

Clone o repositório bookstore-grpc de amostra (em inglês) do GitHub:

Para configurar o Endpoints:

  1. Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço .proto:
    1. Salve uma cópia de bookstore.proto do repositório de exemplo. Esse arquivo define a API do serviço Bookstore.
    2. Crie o seguinte diretório: mkdir generated_pb2
    3. Crie o arquivo de descritor api_descriptor.pb usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde você salvou 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
          

      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 salvou bookstore.proto.

  2. Crie um arquivo YAML de configuração da API gRPC:
    1. Salve uma cópia do arquivo api_config.yaml. Esse arquivo define a configuração da API gRPC do serviço Bookstore.
    2. 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 em bookstore.proto dentro do pacote endpoints.examples.bookstore. O nome da API totalmente qualificado é endpoints.examples.bookstore.Bookstore, assim como aparece no arquivo api_config.yaml.

          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. Verifique se você está no diretório onde os arquivos api_descriptor.pb e api_config.yaml estão localizados.
  2. 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
    
  3. Implante o arquivo proto descriptor e o arquivo de configuração usando a ferramenta de linha de comando gcloud:
    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 de configuração exclusivo do 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 e bookstore.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
endpoints.googleapis.com Google Cloud Endpoints

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
gcloud services enable endpoints.googleapis.com

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar ENDPOINTS_SERVICE_NAME, você pode:

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

  • Para OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da sua especificação do OpenAPI. Para gRPC, a ENDPOINTS_SERVICE_NAME é o que você especificou no campo name de sua 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 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

Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.

  1. 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
        
  2. Altere o diretório de trabalho:

    cd python-docs-samples/endpoints/bookstore-grpc/
        
  3. Instale as dependências:

    pip install virtualenv
        virtualenv env
        source env/bin/activate
        python -m pip install -r requirements.txt
        
  4. Envie uma solicitação à API de amostra:

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

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

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

Como fazer a limpeza

Para evitar cobranças dos recursos usados neste tutorial na sua conta do Google Cloud Platform:

  1. Exclua a API:
    gcloud endpoints services delete SERVICE_NAME
    

    Substitua SERVICE_NAME pelo nome do serviço.

  2. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar a página "Instâncias de VMs"

  3. Marque a caixa de seleção da a instância que você quer excluir.
  4. Clique em Excluir para excluir a instância.

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: