Primeiros passos com o Endpoints para Compute Engine com ESP

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 Liberar espaço.

Custos

Neste documento, você vai 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.

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

  1. 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.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Anote o código do projeto, ele será necessário mais tarde.
  4. Instale e inicialize a Google Cloud CLI.
  5. Atualize a CLI gcloud e instale os componentes do Endpoints:
    gcloud components update
  6. 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 do navegador que se abre, selecione uma conta.
  7. 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.

  8. 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 Google Cloud , acesse a página Criar uma instância.

      Acesse "Criar uma instância"

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

      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.

    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.

Como configurar o Endpoints

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

Para configurar o Endpoints:

  1. 通过服务 .proto 文件创建一个独立的 protobuf 描述符文件:
    1. 保存示例代码库中 bookstore.proto 的副本。此文件用于定义 Bookstore 服务的 API。
    2. 创建以下目录:mkdir generated_pb2
    3. 使用 protoc Protocol Buffers 编译器创建描述符文件 api_descriptor.pb。在您保存了 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

      在前面的命令中,--proto_path 设置为当前工作目录。在 gRPC 编译环境中,如果对 .proto 输入文件使用其他目录,请更改 --proto_path,以便编译器搜索您保存了 bookstore.proto 文件的目录。

  2. 创建 gRPC API 配置 YAML 文件:
    1. 保存 api_config.yaml 文件的副本。此文件用于定义 Bookstore 服务的 gRPC API 配置。
    2. 将 api_config.yaml 文件中的 MY_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      请注意,此文件中 apis.name 字段的值应该与 .proto 文件中的完全限定 API 名称完全匹配;否则部署将无法正常运行。Bookstore 服务是在 endpoints.examples.bookstore 包内的 bookstore.proto 中定义的。其完全限定的 API 名称为 endpoints.examples.bookstore.Bookstore,与其在 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. 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.

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 as configurações de serviço implantadas mais recentes. 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

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
    

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.

  1. Exclua a API:
    gcloud endpoints services delete SERVICE_NAME

    SERVICE_NAME pelo nome do serviço;

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

    Acessar instâncias de VM

  3. Marque a caixa de seleção da instância que você quer excluir.
  4. Para excluir a instância, clique em Mais ações, clique em Excluir e siga as instruções.

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: