本教程介绍如何使用 Extensible Service Proxy (ESP) 将一个简单的示例 gRPC 服务部署到不在 Google Cloud 上运行的 Kubernetes 集群中。本教程使用 Python 版本的 bookstore-grpc
示例。如需其他语言的 gRPC 示例,请参阅后续步骤部分。
本教程使用了示例代码和 ESP 的预构建容器映像,这些映像存储在 Artifact Registry 中。如果您不熟悉容器,请参阅以下内容了解详情:
如需大致了解 Cloud Endpoints,请参阅 Endpoints 简介和 Endpoints 架构。
目标
学习本教程时,请使用以下概要任务列表。为确保请求成功发送到 API,您必须完成所有任务。
- 设置 Google Cloud 项目,然后下载所需的软件。请参阅准备工作。
- 复制并配置
bookstore-grpc
示例中的文件。请参阅配置 Cloud Endpoints。 - 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
- 为您的 Endpoints 服务创建凭据。请参阅为您的服务创建凭据。
- 创建后端,以提供 API 并部署 API。请参阅部署 API 后端。
- 获取服务的外部 IP 地址。请参阅获取服务的外部 IP 地址。
- 向 API 发送请求。请参阅向 API 发送请求。
- 避免系统向您的 Google Cloud 账号收费。请参阅清理。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
您可使用价格计算器根据您的预计使用情况来估算费用。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
准备工作
本教程假设您已经设置了 Minikube 或 Kubernetes 集群。如需了解详情,请参阅 Kubernetes 文档。
- 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- 记下 Google Cloud 项目 ID,因为以后需要它。
- 安装并初始化 gcloud CLI。
- 更新 gcloud CLI 并安装 Endpoints 组件。
gcloud components update
- 确保 Google Cloud CLI (
gcloud
) 有权访问您在 Google Cloud 上的数据和服务: 在浏览器打开的新标签页中,选择一个账号。gcloud auth login
- 将默认项目设置为您的项目 ID:
gcloud config set project YOUR_PROJECT_ID
将
YOUR_PROJECT_ID
替换为您的 Google Cloud 项目 ID。如果您有其他 Google Cloud 项目,并且想要使用
gcloud
管理它们,请参阅 管理 gcloud CLI 配置。 - 安装
kubectl
:gcloud components install kubectl
- 获取用于应用默认凭据的新用户凭据。需要用户凭据才能授权
kubectl
。gcloud auth application-default login
- 在浏览器打开的新标签页中,选择一个账号。
- 按照 gRPC Python 快速入门中的步骤安装 gRPC 和 gRPC 工具。
配置 Endpoints
通过
bookstore-grpc
示例包含您需要在本地复制并进行配置的文件。
- 通过服务
.proto
文件创建一个独立的 protobuf 描述符文件:- 保存示例代码库中
bookstore.proto
的副本。此文件用于定义 Bookstore 服务的 API。 - 创建以下目录:
mkdir generated_pb2
- 使用
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
文件的目录。
- 保存示例代码库中
- 创建 gRPC API 配置 YAML 文件:
- 保存
api_config.yaml
文件的副本。此文件用于定义 Bookstore 服务的 gRPC API 配置。 - 将
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 Infrastructure,这是 Google 的基础服务平台,供 Endpoints 及其他服务用来创建并管理 API 和服务。
- 确保您位于
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 控制台中的端点页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。
对于 OpenAPI,ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的
host
字段中指定的值。对于 gRPC,ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的name
字段中指定的值。
如需详细了解 gcloud
命令,请参阅 gcloud
服务。
如果您收到错误消息,请参阅排查 Endpoints 配置部署问题。
如需了解详情,请参阅部署 Endpoints 配置。
为您的服务创建凭据
为了管理您的 API,ESP 和 ESPv2 都需要使用 Service Infrastructure 中的服务。为了调用这些服务,ESP 和 ESPv2 必须使用访问令牌。当您将 ESP 或 ESPv2 部署到 Google Cloud 环境(例如 GKE 或 Compute Engine)时,ESP 和 ESPv2 会通过 Google Cloud 元数据服务为您获取访问令牌。
将 ESP 或 ESPv2 部署到非 Google Cloud 环境时, 例如本地桌面、本地 Kubernetes 集群 提供商,则必须提供服务账号 JSON 文件 包含私钥的网址。ESP 和 ESPv2 使用 服务账号 生成访问令牌,以调用管理 API 所需的服务。
您可以使用 Google Cloud 控制台或 Google Cloud CLI 创建服务账号和私钥文件:
控制台
- 在 Google Cloud 控制台中,打开服务账号页面。
- 点击选择项目。
- 选择在其中创建了 API 的项目,并点击打开。
- 点击 + 创建服务账号。
- 在服务账号名称字段中,输入您的服务账号的名称。
- 点击创建。
- 点击继续。
- 点击完成。
- 点击新创建的服务账号的电子邮件地址。
- 点击密钥。
- 依次点击添加密钥和创建新密钥。
点击创建。JSON 密钥文件将下载到您的计算机上。
务必要安全存储密钥文件,因为它能够以服务账号的身份进行身份验证。您可以根据需要移动并重命名此文件。
点击关闭。
gcloud
输入以下命令,以显示 Google Cloud 项目的 ID:
gcloud projects list
替换以下命令中的 PROJECT_ID,以将默认项目设置为您的 API 所属的项目:
gcloud config set project PROJECT_ID
确保 Google Cloud CLI (
gcloud
) 有权访问您在 Google Cloud 上的数据和服务:gcloud auth login
如果您有多个账号,请务必选择 API 所属的 Google Cloud 项目中的账号。如果运行
gcloud auth list
,则您选择的账号将显示为该项目的活跃账号。如需创建服务账号,请运行以下命令,并将 SERVICE_ACCOUNT_NAME 和
My Service Account
分别替换为您要使用的名称和显示名:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
该命令将采用以下格式指定服务账号的电子邮件地址:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
后续命令会用到此电子邮件地址。
创建服务账号密钥文件:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
添加所需的 IAM 角色:
本部分介绍 ESP 和 ESPv2 使用的 IAM 资源,以及关联的服务账号访问这些资源所需的 IAM 角色。
端点服务配置
ESP 和 ESPv2 调用使用端点服务配置的 Service Control。端点服务配置是 IAM 资源,ESP 和 ESPv2 需要 Service Controller 角色才能访问它。
IAM 角色属于端点服务配置,而非项目。一个项目可能有多个端点服务配置。
使用以下 gcloud 命令将角色添加到端点服务配置的关联服务账号。
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
其中
* SERVICE_NAME
是端点服务名称
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
是关联的服务账号。
Cloud Trace
ESP 和 ESPv2 调用 Cloud Trace 服务以将 Trace 导出到项目。此项目称为跟踪项目。在 ESP 中,跟踪项目和拥有端点服务配置的项目是相同的。在 ESPv2 中,跟踪项目可通过 --tracing_project_id
标志指定,默认为部署项目。
ESP 和 ESPv2 需要 Cloud Trace Agent 角色才能启用 Cloud Trace。
使用以下 gcloud 命令将该角色添加到关联的服务账号:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
地点
* TRACING_PROJECT_ID 是跟踪项目 ID
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
是关联的服务账号。
如需了解详情,请参阅什么是角色和权限?
如需详细了解这些命令,请参阅 gcloud iam service-accounts
。
部署 API 后端
目前,您已将服务配置部署到 Service Management,但尚未部署将提供 API 后端的代码。本部分逐步介绍如何将示例 API 和 ESP 的预构建容器部署到 Kubernetes。
为 ESP 提供服务凭据
ESP 在容器内部运行,并且需要访问存储在本地 service-account-creds.json
文件中的凭据。为了提供
ESP 有权访问这些凭据,则创建一个
Kubernetes Secret
并将 Kubernetes Secret 作为
Kubernetes 卷。
要创建 Kubernetes 密钥并装载卷,请执行以下操作:
如果您使用 Google Cloud 控制台创建服务账号,请将 JSON 文件重命名为
service-account-creds.json
。将其移至api_descriptor.pb
和api_config.yaml
文件所在的目录。使用服务账号凭据创建 Kubernetes 密钥:
kubectl create secret generic service-account-creds --from-file=service-account-creds.json
成功时,您会看到如下消息:
secret "service-account-creds" created
。
用于将 API 和 ESP 部署到 Kubernetes 的部署清单文件已包含 Secret 卷,如该文件的以下两个部分所示:
配置服务名称并启动服务
ESP 需要知道您的服务名称,才能找到您之前使用 gcloud endpoints services deploy
命令部署的配置。
要配置服务名称并启动服务,请执行以下操作:
将部署清单文件
k8s-grpc-bookstore.yaml
的一个副本保存到service-account-creds.json
所在的目录中。打开
k8s-grpc-bookstore.yaml
并将 SERVICE_NAME 替换为您的 Endpoints 服务的名称。此名称与您在api_config.yaml
文件的name
字段中配置的名称相同。--rollout_strategy=managed
选项 将 ESP 配置为使用最新部署的服务配置。指定此选项后,在部署新的服务配置后,ESP 最多会在 5 分钟内检测到更改并自动开始使用该服务配置。建议您指定此选项,而不是指定特定配置 ID 供 ESP 使用。如需详细了解 ESP 参数,请参阅 ESP 启动选项。启动服务以在 Kubernetes 上部署服务:
kubectl create -f k8s-grpc-bookstore.yaml
如果您看到类似以下内容的错误消息:
The connection to the server localhost:8080 was refused - did you specify the right host or port?
这表示未正确配置
kubectl
。请参阅 配置kubectl
。
获取服务的外部 IP 地址
如需向示例 API 发送请求,您需要具备服务的外部 IP 地址。在容器中启动服务后,外部 IP 地址可能需要过几分钟才可以使用。
查看外部 IP 地址:
kubectl get service
请记下
EXTERNAL-IP
的值,并将其保存在 SERVER_IP 环境变量中,与向示例 API 发送请求时一样。export SERVER_IP=YOUR_EXTERNAL_IP
向 API 发送请求
要向示例 API 发送请求,您可以使用以 Python 编写的示例 gRPC 客户端。
克隆托管 gRPC 客户端代码的 Git 代码库:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
切换您的工作目录:
cd python-docs-samples/endpoints/bookstore-grpc/
安装依赖项:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
向示例 API 发送一个请求:
python bookstore_client.py --host SERVER_IP --port 80
在 Endpoints > 服务页面中查看 API 的活动图表。
请求可能需要一些时间才能体现在图表中。
在“日志浏览器”页面中查看 API 的请求日志。
如果未成功收到响应,请参阅排查响应错误。
您刚刚在 Endpoints 中部署并测试了一个 API!
清除数据
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。
删除 API:
gcloud endpoints services delete SERVICE_NAME
将 SERVICE_NAME 替换为您的 API 名称。
删除 GKE 集群:
gcloud container clusters delete NAME --zone ZONE
后续步骤
- 了解如何 配置您自己的 gRPC API 。
- 配置 DNS:
- 认真阅读 GitHub 上的 Bookstore 示例应用。客户端和服务器均有 Python 版和 Java 版。
- GitHub 上以下列语言提供了
getting-started-grpc
示例: