Começar a usar o gRPC do Cloud Endpoints para o grupo de instâncias gerido com o ESPv2

Este tutorial mostra como implementar um exemplo simples de um serviço gRPC com o Extensible Service Proxy V2 (ESPv2) num grupo de instâncias gerido.

Este tutorial usa a versão Python do exemplo bookstore-grpc. Consulte a secção O que se segue para ver exemplos de gRPC noutros idiomas.

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Configurar pontos finais

Clone o bookstore-grpcrepositório de amostra do GitHub.

Para configurar pontos finais:

  1. Crie um ficheiro de descritor protobuf autónomo a partir do ficheiro .proto do seu serviço:
    1. Guarde uma cópia de bookstore.proto do repositório de exemplo. Este ficheiro define a API do serviço Bookstore.
    2. Crie o seguinte diretório: mkdir generated_pb2
    3. Crie o ficheiro de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde guardou 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 seu ambiente de compilação gRPC, se usar um diretório diferente para os ficheiros de entrada, altere --proto_path para que o compilador pesquise o diretório onde guardou bookstore.proto..proto

  2. Crie um ficheiro YAML de configuração da API gRPC:
    1. Guarde uma cópia do api_config.yamlficheiro. Este ficheiro define a configuração da API gRPC para o serviço Bookstore.
    2. Substitua MY_PROJECT_ID no ficheiro api_config.yaml pelo ID do projeto. Google Cloud Por exemplo: 
      #
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog

      Tenha em atenção que o valor do campo apis.name neste ficheiro corresponde exatamente ao nome da API totalmente qualificado do ficheiro .proto. Caso contrário, a implementação não funciona. O serviço Bookstore está definido em bookstore.proto no pacote endpoints.examples.bookstore. O nome da API totalmente qualificado é endpoints.examples.bookstore.Bookstore, tal como aparece no ficheiro api_config.yaml.

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

Consulte o artigo Configurar pontos finais para mais informações.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

  1. Certifique-se de que está no diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.
  2. Confirme que o projeto predefinido que a ferramenta de linha de comandos gcloud está a usar atualmente é o projeto Google Cloud no qual quer implementar a configuração do Endpoints. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado. 
    gcloud config list project

    Se precisar de alterar o projeto predefinido, execute o seguinte comando:

    gcloud config set project YOUR_PROJECT_ID
  3. Implemente o ficheiro proto descriptor e o ficheiro de configuração através da CLI do Google Cloud: 
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

    À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:

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

    CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por 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 ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar novamente a configuração dos Endpoints no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço.

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:
Nome Título
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

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

  • Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.

  • Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

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

gcloud services list

Se não vir os serviços necessários listados, ative-os:

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

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

  • Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.

  • Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

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

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais. Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.

Implementar o back-end da API

Até agora, implementou a configuração da API na gestão de serviços, mas ainda não implementou o código que serve o back-end da API. Esta secção explica como configurar o Docker no seu grupo de instâncias gerido e executar o código de back-end da API e o ESPv2 num contentor Docker.

Crie um modelo de instância

Crie um modelo que vai usar para criar um grupo de instâncias de VM. Cada instância criada a partir do modelo inicia um ESPv2 e um servidor de aplicações de back-end.

  1. Na Google Cloud consola, aceda à página Modelos de instâncias.

    Aceda a Modelos de instâncias

  2. Clique em Criar modelo de instância.

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

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

  5. Em Disco de arranque, defina a Imagem como Container Optimized OS stable version.

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

  7. Clique em Gestão, segurança, discos, trabalhar em rede, arrendamento único para revelar as definições avançadas.

  8. Clique no separador Gestão. Em Automatização, introduza o seguinte: Script de arranque. Lembre-se de atualizar o 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 obtém, instala e inicia o servidor de aplicações de eco e o servidor proxy ESPv2 no arranque da instância.

  9. Clique em Criar.

Aguarde até que o modelo seja criado antes de continuar.

Crie um grupo de instâncias gerido regional

Para executar a aplicação, use o modelo de instância para criar um grupo de instâncias gerido regional:

  1. Na Google Cloud consola, aceda à página Grupos de instâncias.

    Aceda a Grupos de instâncias

  2. Clique em Criar grupo de instâncias.

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

  4. Em Localização, selecione Várias zonas.

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

  6. Clique no menu pendente Configurar zonas para revelar 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 Ajuste de escala automático, selecione Não ajustar a escala automaticamente.

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

  10. Em Redistribuição de instâncias, selecione Ativada.

  11. Em Reparação automática e Verificação de estado, selecione Sem verificação de estado.

  12. Clique em Criar. Esta ação redireciona novamente para a página Grupos de instâncias.

Crie um balanceador de carga

Esta secção explica os passos necessários para criar um equilibrador de carga regional que direcione o tráfego TCP para o seu grupo de instâncias.

  1. Na Google Cloud consola, aceda à página Criar um balanceador de carga.

    Aceda a Crie um balanceador de carga

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

  3. Em Acessível pela Internet ou apenas interno, selecione Da Internet para as minhas VMs.

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

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

  6. Clique em Continuar.

  7. Em Nome, introduza 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 funcionamento, crie uma nova verificação de funcionamento.

    • Em nome, introduza espv2-load-balancer-check.
    • Confirme se o Protocolo é TCP e se a Porta é 80.

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

  12. Em Rever e finalizar, valide

    • O grupo de instâncias está load-balancing-espv2-group.
    • A região é us-central1.
    • O protocolo é TCP.
    • O IP:Porta é EPHEMERAL:80.

  13. Depois de criar o balanceador de carga, encontre o endereço IP na página Balanceador de carga.

    Aceder ao balanceador de carga

Enviar um pedido para a API

Se estiver a enviar o pedido a partir da mesma instância em que os contentores do Docker estão a ser executados, pode substituir SERVER_IP por localhost. Caso contrário, substitua SERVER_IP pelo IP externo da instância.

Pode encontrar o endereço IP externo executando o seguinte comando:

gcloud compute instances list

Para enviar pedidos para a API de exemplo, pode usar um cliente gRPC de exemplo escrito em Python.

  1. Clone o repositório Git onde o código do cliente gRPC está alojado:

    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. Instalar dependências: 

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

  4. Envie um pedido para a API de exemplo:

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

Se não receber uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!