使用入门:Compute Engine 上使用 ESPv2 的 Endpoints

本教程介绍如何在 Compute EngineDocker 容器中部署简单的示例 gRPC 服务和 Extensible Service Proxy V2 Beta 版(ESPv2 Beta 版)。

本教程使用 Python 版本的 bookstore-grpc 示例。如需其他语言的 gRPC 示例,请参阅后续步骤部分。

如需大致了解 Cloud Endpoints,请参阅 Endpoints 简介Endpoints 架构

目标

学习本教程时,请使用以下概要任务列表。为确保请求成功发送到 API,您必须完成所有任务。

  1. 设置 Google Cloud 项目,然后下载所需的软件。请参阅准备工作
  2. 创建 Compute Engine 虚拟机实例。请参阅创建 Compute Engine 实例
  3. 复制并配置 bookstore-grpc 示例中的文件。请参阅配置 Endpoints
  4. 部署 Endpoints 配置以创建一个 Endpoints 服务。请参阅部署 Endpoints 配置
  5. 在 Compute Engine 虚拟机上部署 API 和 ESPv2 Beta 版。请参阅部署 API 后端
  6. 向 API 发送请求。请参阅向 API 发送请求
  7. 避免系统向您的 Google Cloud 帐号收费。请参阅清理

费用

本教程使用 Google Cloud 的以下收费组件:

您可使用价格计算器根据您的预计使用量来估算费用。 Google Cloud 新用户可能有资格申请免费试用

完成本教程后,您可以删除所创建的资源以避免继续计费。如需了解详情,请参阅清理

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册一个新帐号

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Google Cloud 项目已启用结算功能。 了解如何确认您的项目已启用结算功能

  4. 记下项目 ID,您稍后需要用到。
  5. 安装并初始化 Cloud SDK
  6. 更新 Cloud SDK 并安装 Endpoints 组件:
    gcloud components update
  7. 确保 Cloud SDK (gcloud) 有权访问您在 Google Cloud 上的数据和服务:
    gcloud auth login
    在浏览器打开的新标签页中,选择一个帐号。
  8. 将默认项目设置为您的项目 ID。
    gcloud config set project YOUR_PROJECT_ID

    YOUR_PROJECT_ID 替换为项目 ID。如果您有其他 Google Cloud 项目,并且想用 gcloud 管理这些项目,请参阅管理 Cloud SDK 配置

  9. 按照 gRPC Python 快速入门中的步骤安装 gRPC 和 gRPC 工具。

完成本教程后,您可以删除所创建的资源以避免继续计费。如需了解详情,请参阅清理

创建 Compute Engine 实例

要创建 Compute Engine 实例,请执行以下操作:

  1. 在 Cloud Console 中,转到虚拟机实例页面。

    转到“虚拟机实例”页面

  2. 点击创建实例
  3. 防火墙部分中,选择 允许 HTTP 流量允许 HTTPS 流量
  4. 点击创建以创建实例。
  5. 已设置所需选项的虚拟机实例创建窗口的屏幕截图

    实例启动需要您稍等片刻。准备就绪后,该实例将在虚拟机实例页面上列出,并显示绿色状态图标。

  6. 确保您可以连接到虚拟机实例。
  7. 现在,您可以使用终端在 Debian 实例上运行 Linux 命令。
  8. 输入 exit 以断开与该实例的连接。
  • 请记下实例名称、地区和外部 IP 地址,因为您稍后需要用到。
  • 配置 Endpoints

    从 GitHub 克隆 bookstore-grpc 示例代码库。

    如需配置 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
        

    如需了解详情,请参阅配置 Endpoints

    部署 Endpoints 配置

    如需部署 Endpoints 配置,请使用 gcloud endpoints services deploy 命令。此命令使用 Service Management 创建一项托管式服务。

    1. 确保您位于 api_descriptor.pbapi_config.yaml 文件所在的目录中。
    2. 确认 gcloud 命令行工具当前使用的默认项目是您要向其部署 Endpoints 配置的 Google Cloud 项目。验证从以下命令返回的项目 ID,以确保不会在错误的项目中创建服务。
      gcloud config list project
      

      如果您需要更改默认项目,请运行以下命令:

      gcloud config set project YOUR_PROJECT_ID
      
    3. 使用 gcloud 命令行工具部署 proto descriptor 文件和配置文件:
      gcloud endpoints services deploy api_descriptor.pb api_config.yaml
      

      在创建和配置服务时,Service Management 会向终端输出信息。部署完成后,系统将显示如下所示的消息:

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

      CONFIG_ID 是部署创建的唯一 Endpoints 服务配置 ID。例如:

      Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
      

      在前面的示例中,2017-02-13r0 是服务配置 ID,bookstore.endpoints.example-project.cloud.goog 是服务名称。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 Endpoints 配置,服务配置 ID 中的修订版本号将递增。

    检查所需服务

    Endpoints 和 ESP 至少需要启用以下 Google 服务:
    姓名 说明
    servicemanagement.googleapis.com Service Management API
    servicecontrol.googleapis.com Service Control API
    endpoints.googleapis.com Google Cloud Endpoints

    在大多数情况下,gcloud endpoints services deploy 命令会启用这些必需的服务。但在以下情况下,gcloud 命令会成功完成,但不启用必需的服务:

    • 您使用了 Terraform 之类的第三方应用,但未添加这些服务。

    • 您将 Endpoints 配置部署到已明确停用这些服务的现有 Google Cloud 项目。

    使用以下命令确认必需服务是否已启用:

    gcloud services list

    如果您没有看到列出的必需服务,请启用它们:

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

    同时启用 Endpoints 服务:

    gcloud services enable ENDPOINTS_SERVICE_NAME

    要确定 ENDPOINTS_SERVICE_NAME,您可以执行以下任一操作:

    • 部署 Endpoints 配置后,转到 Cloud Console 中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。

    • 对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的 host 字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的 name 字段中指定的值。

    如需详细了解 gcloud 命令,请参阅 gcloud 服务

    如果您收到错误消息,请参阅排查 Endpoints 配置部署问题。 如需了解详情,请参阅部署 Endpoints 配置

    部署 API 后端

    到目前为止,您已将 API 配置部署到 Service Management,但尚未部署将服务 API 后端的代码。本部分逐步介绍如何在虚拟机实例上安装 Docker,以及如何在 Docker 容器中运行 API 后端代码和 ESPv2 Beta 版。

    在虚拟机实例上安装 Docker

    要在虚拟机实例上安装 Docker,请执行以下操作:

    1. 运行以下命令,以便为您的项目设置地区:
      gcloud config set compute/zone YOUR_INSTANCE_ZONE
      

      YOUR_INSTANCE_ZONE 替换为运行实例的地区。

    2. 使用以下命令连接到实例:
      gcloud compute ssh INSTANCE_NAME
      

      INSTANCE_NAME 替换为虚拟机实例的名称。

    3. 如需设置 Docker 代码库,请参阅 Docker 文档。请务必按照与虚拟机实例的版本和架构相对应的步骤进行操作:
      • Jessie 或更高版本
      • x86_64/amd64

    在 Docker 容器中运行示例 API 和 ESPv2 Beta 版

    要在 Docker 容器中运行示例 gRPC 服务和 ESPv2 Beta 版以供客户端使用,请执行以下操作:

    1. 在虚拟机实例中,创建您自己的名为 esp_net 的容器网络。
      sudo docker network create --driver bridge esp_net
      
    2. 运行用于提供示例 API 的示例 Bookstore 服务器:
      sudo docker run \
          --detach \
          --name=bookstore \
          --net=esp_net \
          gcr.io/endpointsv2/python-grpc-bookstore-server:1
      
    3. 运行预封装的 ESPv2 Beta 版 Docker 容器。在 ESPv2 Beta 版启动选项中,将 SERVICE_NAME 替换为您的服务名称。此名称与您在 api_config.yaml 文件的 name 字段中配置的名称相同。例如: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
      

      --rollout_strategy=managed 选项将 ESPv2 Beta 版配置为使用最新部署的服务配置。如果指定此选项,则 ESPv2 Beta 版会在您部署新服务配置后的一分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项,而不是提供特定配置 ID 供 ESPv2 Beta 版使用。如需详细了解 ESPv2 Beta 版参数,请参阅 ESPv2 Beta 版启动选项

    如果您收到错误消息,请参阅排查 Compute Engine 上的 Endpoints 问题

    向 API 发送请求

    如果您从运行 Docker 容器的同一实例中发送请求,则可以将 SERVER_IP 替换为 localhost。否则,将 SERVER_IP 替换为实例的外部 IP。

    您可以通过运行以下命令找到外部 IP 地址:

    gcloud compute instances list
    

    要向示例 API 发送请求,您可以使用以 Python 编写的示例 gRPC 客户端。

    1. 克隆托管 gRPC 客户端代码的 Git 代码库:

      git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
         

    2. 切换您的工作目录:

      cd python-docs-samples/endpoints/bookstore-grpc/
        

    3. 安装依赖项:

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

    4. 向示例 API 发送一个请求:

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

    如果未获得成功响应,请参阅排查响应错误

    您刚刚在 Endpoints 中部署并测试了一个 API!

    清理

    为避免因本教程中使用的资源导致您的 Google Cloud Platform 帐号产生费用,请执行以下操作:

    1. 删除 API:
      gcloud endpoints services delete SERVICE_NAME
      

      SERVICE_NAME 替换为您的服务名称。

    2. 在 Cloud Console 中,转到虚拟机实例页面。

      转到“虚拟机实例”页面

    3. 点击您要删除的实例对应的复选框。
    4. 点击删除 以删除实例。

    后续步骤