Primeiros passos com o gRPC do Cloud Endpoints para o grupo gerenciado de instâncias com o ESPv2

OpenAPI | gRPC

Neste tutorial, mostramos como implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy V2 (ESPv2) em um grupo gerenciado de instâncias.

A versão Python da amostra bookstore-grpc é utilizada neste tutorial. 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.

Como configurar o Endpoints

Clone o repositório bookstore-grpc de amostra 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 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 Google Cloud em que você quer 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 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 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

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 no grupo gerenciado de instâncias e executar o código de back-end da API e o ESPv2 em um contêiner do Docker.

Criar um modelo de instância

Crie um modelo que você usará para criar um grupo de instâncias da VM. Cada instância criada a partir do modelo inicia um ESPv2 e um servidor de aplicativos de back-end.

1. No console do Google Cloud , acesse a página Modelos de instância.

   Acesse Modelos de instância

2. Clique em Criar modelo de instância.

3. Em Nome, insira load-balancing-espv2-template.

4. Em Configuração da máquina, defina o Tipo de máquina como e2-micro.

5. Em Disco de inicialização, defina a Imagem como Container Optimized OS stable version.

6. Em Firewall, selecione Permitir tráfego HTTP.

7. Clique em Gerenciamento, segurança, discos, rede, locatário único para ver configurações avançadas.

8. Clique na guia Gerenciamento. Em Automação, insira o script de inicialização a seguir. Lembre-se de atualizar ENDPOINTS_SERVICE_NAME.

   sudo docker network create --driver bridge esp_net
   sudo docker run \
     --detach \
     --name=bookstore \
     --net=esp_net \
     gcr.io/endpointsv2/python-grpc-bookstore-server:1
   sudo docker run \
     --detach \
     --name=esp \
     --publish=80:9000 \
     --net=esp_net \
     gcr.io/endpoints-release/endpoints-runtime:2 \
     --service=ENDPOINTS_SERVICE_NAME \
     --rollout_strategy=managed \
     --listener_port=9000 \
     --healthz=/healthz \
     --backend=grpc://bookstore:8000
   

   O script recebe, instala e inicia o servidor de aplicativos de eco e o servidor proxy ESPv2 na inicialização da instância.

9. Clique em Criar.

Aguarde o modelo ser criado para continuar.

Criar um grupo de instâncias gerenciadas regional

Para executar o aplicativo, use o modelo de instância para criar um grupo gerenciado de instâncias regional:

1. No console, do Google Cloud , acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Clique em Criar grupo de instâncias.

3. Em Nome, insira load-balancing-espv2-group.

4. Em Local, selecione Várias zonas.

   Dica profissional: para garantir que seu aplicativo esteja disponível durante eventos extremos, como interrupções de zona, o Compute Engine recomenda que você distribua o aplicativo em várias zonas.

5. Em Região, selecione us-central1.

6. Clique no menu suspenso Configurar zonas para exibir Zonas. Selecione as seguintes zonas:

   • us-central1-b
   • us-central1-c
   • us-central1-f

7. Em Modelo de instância, selecione load-balancing-espv2-template.

8. Em Escalonamento automático, selecione Não fazer escalonamento automático.

9. Defina o Número de instâncias como 3.

   Dica profissional: ao criar um grupo regional de instâncias gerenciadas com o Compute Engine, é recomendável provisionar instâncias suficientes. Assim, caso todas elas em qualquer zona estejam indisponíveis, as instâncias restantes ainda serão o mínimo necessário. No entanto, provisionar mais instâncias do que você precisa pode resultar em custos adicionais. Para mais informações, consulte Como selecionar o tamanho do grupo de instâncias para garantir a disponibilidade.

10. Em Redistribuição da instância, selecione Ativado.

11. Em Recuperação automática e Verificação de integridade, selecione Nenhuma verificação de integridade.

12. Clique em Criar. Isso redireciona você de volta à página Grupos de instâncias.

    Observação: aguarde alguns minutos até que todas as instâncias do grupo estejam em execução e prontas para exibir o aplicativo da Web.

Criar um balanceador de carga

Nesta seção, explicamos as etapas necessárias para criar um balanceador de carga regional que direciona o tráfego TCP para seu grupo de instâncias.

1. No console do Google Cloud , acesse a página Criar um balanceador de carga.

   Acessar "Criar um balanceador de carga"

2. Em Balanceamento de carga TCP, clique em Iniciar configuração.

3. Em Somente voltado para a Internet ou interno, selecione Da Internet para minhas VMs.

4. Em Várias regiões ou região única, selecione Apenas uma região.

5. Em Tipo de back-end, selecione Serviço de back-end.

6. Clique em Continuar.

7. Em Nome, insira espv2-load-balancer.

8. Em Configuração de back-end, selecione a região us-central1.

9. Selecione o grupo de instâncias load-balancing-espv2-group.

10. Em Verificação de integridade, crie uma verificação de integridade.

    • Em Nome, insira espv2-load-balancer-check.
    • Confirme se Protocolo é TCP e se Porta é 80.

11. Em Configuração de front-end, digite o número da porta 80.

12. Em Analisar e finalizar, verifique:

    • se o Grupo de instâncias é load-balancing-espv2-group;
    • se a Região é us-central1;
    • se o Protocolo é TCP;
    • se o IP:Porta é EPHEMERAL:80.

13. Depois que o balanceador de carga for criado, localize o endereço IP na página Balanceador de carga.

    Acessar "Balanceador de carga"

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.

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
   

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

     Acessar a 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.

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.