使用 ESPv2 为 Cloud Run 设置 Cloud Endpoints gRPC
本页面介绍如何使用 gRPC 后端为 Cloud Run 设置 Cloud Endpoints。Endpoints 使用 Extensible Service Proxy V2 (ESPv2) 作为 API 网关。如需为 Cloud Run 提供 API 管理功能,请将预构建的 ESPv2 容器部署到 Cloud Run。然后,使用 Cloud Run IAM 保护服务,以便 ESPv2 可调用它们。
如此设置之后,ESPv2 会拦截向您服务发出的所有请求,并在调用服务之前执行任何必要的检查(如身份验证)。当服务响应时,ESPv2 会收集并报告遥测数据,如下图所示。您可以在 Google Cloud 控制台的 端点 > 服务页面上查看服务的指标。
如需大致了解 Cloud Endpoints,请参阅 Endpoints 简介和 Endpoints 架构。
迁移到 ESPv2
以前版本的 Cloud Endpoints 在使用 ESP 的 Cloud Run 上不支持 gRPC。 要使用此功能,请迁移到 Extensible Service Proxy V2。
任务列表
学习本教程时,请使用以下任务列表。完成本教程所需的所有任务。
- 创建一个 Google Cloud 项目,如果您尚未部署自己的 Cloud Run,请部署一个示例后端 gRPC 服务。请参阅准备工作。
- 为 ESPv2 服务预留 Cloud Run 主机名。请参阅预留 Cloud Run 主机名。
- 创建描述您的 API 的 gRPC API 配置文档,并配置到您的 Cloud Run 的路由。请参阅配置 Endpoints。
- 部署 gRPC API 配置文档以创建托管式服务。 请参阅部署 Endpoints 配置。
- 使用您的 Endpoints 服务配置构建新的 ESPv2 Docker 映像。请参阅构建新的 ESPv2 映像。
- 将 ESPv2 容器部署到 Cloud Run。然后为 ESPv2 授予 Identity and Access Management (IAM) 权限以调用您的服务。请参阅部署 ESPv2 容器。
- 调用一个服务。请参阅向 API 发送请求。
- 跟踪您的服务的活动。请参阅跟踪 API 活动。
- 避免向您的 Google Cloud 账号收取费用。请参阅清理。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
您可使用价格计算器根据您的预计使用情况来估算费用。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
准备工作
如需进行设置,请执行以下操作:
在 Google Cloud 控制台中,转到管理资源页面并创建项目。
确保您的项目已启用结算功能。
请记下项目 ID,您稍后需要用到它。在本页面的其余部分,此项目 ID 称为 ESP_PROJECT_ID。
请记下项目编号,您稍后会用到它。在本页面的其余部分,此项目编号称为 ESP_PROJECT_NUMBER。
下载并安装 Google Cloud CLI。
按照 gRPC Python 快速入门中的步骤安装 gRPC 和 gRPC 工具。
部署 python-grpc-bookstore-server 示例后端 gRPC Cloud Run 服务以用于本教程。gRPC 服务使用以下容器映像:
gcr.io/endpointsv2/python-grpc-bookstore-server:2
按照快速入门:部署预建的示例容器中的步骤部署该服务。请务必将该快速入门中指定的容器映像替换为
gcr.io/endpointsv2/python-grpc-bookstore-server:2
有关部署服务的区域和项目 ID 的注释。在本页面的其余部分,此项目 ID 称为 BACKEND_PROJECT_ID。已部署的 Cloud Run 服务的名称为 BACKEND_SERVICE_NAME,其 Cloud Run 主机名称为 BACKEND_HOST_NAME。
预留 Cloud Run 主机名
您必须为 ESPv2 服务预留 Cloud Run 主机名,才能configure OpenAPI 文档或 gRPC 服务配置。为了预留主机名,您需要将示例容器部署到 Cloud Run。稍后,您会将 ESPv2 容器deploy到相同的 Cloud Run 服务中。
-
确保 gcloud CLI 有权访问您的数据和服务。
- 登录。
gcloud auth login
- 在打开的新浏览器标签页中,选择一个帐号,该帐号在您为了将 ESPv2 部署到 Cloud Run 而创建的 Google Cloud 项目中具有 Editor 或 Owner 角色。
- 登录。
-
设置区域。
gcloud config set run/region us-central1
-
将示例映像
gcr.io/cloudrun/hello
部署到 Cloud Run。将 CLOUD_RUN_SERVICE_NAME 替换为您要使用的服务名称。gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/cloudrun/hello" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
成功完成上述操作后,该命令将显示如下所示的消息:
Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL
例如,如果将 CLOUD_RUN_SERVICE_NAME 设置为
gateway
:Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app
在此示例中,
https://gateway-12345-uc.a.run.app
为 CLOUD_RUN_SERVICE_URL,gateway-12345-uc.a.run.app
为 CLOUD_RUN_HOSTNAME。 - 记下 CLOUD_RUN_SERVICE_NAME 和 CLOUD_RUN_HOSTNAME。您稍后会将 ESPv2 部署到 CLOUD_RUN_SERVICE_NAME Cloud Run 服务。您可以在 OpenAPI 文档的
host
字段中指定CLOUD_RUN_HOSTNAME。
配置 Endpoints
bookstore-grpc
示例包含您在本地复制并进行配置所需的文件。
- 通过服务
.proto
文件创建一个独立的 protobuf 描述符文件:- 将示例代码库中
bookstore.proto
的副本保存到当前工作目录。此文件用于定义 Bookstore 服务的 API。 - 在工作目录下创建以下目录:
mkdir generated_pb2
- 使用
protoc
Protocol Buffers 编译器创建描述符文件api_descriptor.pb
。在您保存了bookstore.proto
的目录中运行以下命令:python3 -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
文件的目录。
- 将示例代码库中
-
在您当前的工作目录(即
bookstore.proto
所在的目录)中创建名为api_config.yaml
的文本文件。为方便起见,本页面用此文件名指代 gRPC API 配置文档,但如果您愿意的话,也可以改用其他名称。将以下内容添加到文件中: 缩进对 yaml 格式而言非常重要。例如,# The configuration schema is defined by the service.proto file. # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto type: google.api.Service config_version: 3 name: CLOUD_RUN_HOSTNAME title: Cloud Endpoints + Cloud Run gRPC apis: - name: endpoints.examples.bookstore.Bookstore usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true backend: rules: - selector: "*" address: grpcs://BACKEND_HOST_NAME
name
字段必须与type
处于同一级别。 在
name
字段中,指定 CLOUD_RUN_HOSTNAME,即上面的预留 Cloud Run 主机名中预留的网址的主机名部分。请勿包含协议标识符,例如https://
或grpcs://
。在
backend.rules
部分的address
字段中,将 BACKEND_HOST_NAME 替换为在准备工作中创建的实际 gRPC Bookstore Cloud Run 服务。请记下
api_config.yaml
文件中title
属性的值:title: Cloud Endpoints + Cloud Run gRPC
在您部署配置后,
title
属性的值会成为 Endpoints 服务的名称。- 保存您的 gRPC API 配置文档。
如需了解详情,请参阅配置 Endpoints。
部署 Endpoints 配置
如需部署 Endpoints 配置,请使用 gcloud endpoints services deploy
命令。此命令使用 Service Management 创建一项托管式服务。
- 确保您位于
api_descriptor.pb
和api_config.yaml
文件所在的目录中。 - 确认
gcloud
命令行工具当前使用的默认项目是您要向其部署 Endpoints 配置的 Google Cloud 项目。验证从以下命令返回的项目 ID,以确保不会在错误的项目中创建服务。gcloud config list project
如果您需要更改默认项目,请运行以下命令:
gcloud config set project YOUR_PROJECT_ID
- 使用 Google Cloud CLI 部署
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.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
同时启用 Endpoints 服务:
gcloud services enable ENDPOINTS_SERVICE_NAME
要确定 ENDPOINTS_SERVICE_NAME,您可以执行以下任一操作:
部署 Endpoints 配置后,转到 Cloud 控制台中的 Endpoint 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。
对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的
host
字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的name
字段中指定的值。
如需详细了解 gcloud
命令,请参阅 gcloud
服务。
如果您收到错误消息,请参阅排查 Endpoints 配置部署问题。
如需了解详情,请参阅部署 Endpoints 配置。
构建新的 ESPv2 映像
将 Endpoints 服务配置构建到新的 ESPv2 Docker 映像中。您稍后会将此映像部署到预留的 Cloud Run 服务。
如需将服务配置构建到新的 ESPv2 Docker 映像中,请执行以下操作:
将此脚本下载到安装了 gcloud CLI 的本地机器。
使用以下命令运行脚本:
chmod +x gcloud_build_image
./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_ID
对于 CLOUD_RUN_HOSTNAME,请指定在上文的预留 Cloud Run 主机名中预留的网址的主机名。请勿包含协议标识符
https://
。例如:
chmod +x gcloud_build_image
./gcloud_build_image -s gateway-12345-uc.a.run.app \ -c 2019-02-01r0 -p your-project-id
-
该脚本使用
gcloud
命令下载服务配置,将服务配置构建到新的 ESPv2 映像中,然后将新映像上传到项目 Container Registry 中:脚本会自动使用最新版本的 ESPv2,由输出映像名称中的 ESP_VERSION 表示。输出映像将上传到:gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
例如:
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
部署 ESPv2 容器
使用您在上面构建的新映像部署 ESPv2 Cloud Run 服务。将 CLOUD_RUN_SERVICE_NAME 替换为您在上文的预留 Cloud Run 主机名中最初预留主机名时所用的 Cloud Run 服务名称:
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
如果要将 Endpoints 配置为使用其他 ESPv2 启动选项(例如启用 CORS),您可以在
ESPv2_ARGS
环境变量中传递参数:gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --allow-unauthenticated \ --platform managed \ --project ESP_PROJECT_ID
如需详细了解如何设置
ESPv2_ARGS
环境变量并获取更多相关示例(包括可用选项的列表以及如何指定多个选项的信息),请参阅 Extensible Service Proxy V2 标志。- 为 ESPv2 授予调用 Cloud Run 服务的权限。
对每个服务运行以下命令。在以下命令中:
- 将 BACKEND_SERVICE_NAME 替换为要调用的 Cloud Run 服务的名称。如果您使用的是通过部署 `gcr.io/endpointsv2/python-grpc-bookstore-server:2` 创建的服务,则使用
python-grpc-bookstore-server
作为此值。 - 将 ESP_PROJECT_NUMBER 替换为您针对 ESPv2 创建的项目的编号。如需找到此编号,一种方法是前往 Google Cloud 控制台中的 IAM 页面,然后找到默认计算服务帐号,即“member”标志中使用的服务帐号。
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
- 将 BACKEND_SERVICE_NAME 替换为要调用的 Cloud Run 服务的名称。如果您使用的是通过部署 `gcr.io/endpointsv2/python-grpc-bookstore-server:2` 创建的服务,则使用
如需了解详情,请参阅使用 IAM 管理访问权限。
向 API 发送请求
要向示例 API 发送请求,您可以使用以 Python 编写的示例 gRPC 客户端。
克隆托管 gRPC 客户端代码的 Git 代码库:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
更改您的工作目录:
cd python-docs-samples/endpoints/bookstore-grpc/
安装依赖项:
pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt
向示例 API 发送一个请求:
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
在 CLOUD_RUN_HOSTNAME 中指定 ESPv2 Cloud Run 服务的主机名,不含协议标识符。例如:
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
在 Endpoints > 服务页面中查看 API 的活动图表。
请求可能需要一些时间才能体现在图表中。
在“日志浏览器”页面中查看 API 的请求日志。
如果未获得成功响应,请参阅排查响应错误。
您刚刚在 Endpoints 中部署并测试了一个 API!
跟踪 API 活动
在 Google Cloud 控制台的 端点 > 服务页面上查看 API 的活动图表。
请求可能需要一些时间才能体现在图表中。
在“日志浏览器”页面上查看 API 的请求日志。
为 API 创建开发者门户
可使用 Cloud Endpoints 门户创建开发者门户,该门户是一个可用于与示例 API 进行交互的网站。如需了解详情,请参阅 Cloud Endpoints 门户概览。
清理
为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用,请按照以下步骤操作。
如需了解如何停止本教程使用的服务,请参阅删除 API 和 API 实例。