此页面由 Cloud Translation API 翻译。

使用入门：GKE 上使用 ESPv2 的 Endpoints

OpenAPI | gRPC

本教程将介绍如何利用 Google Kubernetes Engine (GKE) 上的 Extensible Service Proxy V2 (ESPv2) 部署简单的示例 gRPC 服务。本教程使用 Python 版本的 bookstore-grpc 示例。如需其他语言的 gRPC 示例，请参阅后续步骤部分。

本教程使用了示例代码的预构建容器映像， ESPv2 存储服务 Artifact Registry。如果您不熟悉容器，请参阅以下内容了解详情：

如需大致了解 Cloud Endpoints，请参阅 Endpoints 简介和 Endpoints 架构。

目标

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

设置 Google Cloud 项目，然后下载所需的软件。请参阅准备工作。
从 bookstore-grpc 示例。请参阅配置 Endpoints。
部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置。
创建后端，以提供 API 并部署 API。请参阅部署 API 后端。
获取服务的外部 IP 地址。请参阅获取服务的外部 IP 地址。
向 API 发送请求。请参阅向 API 发送请求。
避免向您的 Google Cloud 账号收取费用。请参阅清理。

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

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

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

记下 Google Cloud 项目 ID，因为以后需要它。
安装并初始化 Google Cloud 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 替换为您的项目 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 描述符文件：
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 文件的目录。
创建 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 创建一项托管式服务。

确保您位于 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.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 控制台中的 Endpoints 页面。服务名称列下显示了可能的 ENDPOINTS_SERVICE_NAME 列表。
对于 OpenAPI，ENDPOINTS_SERVICE_NAME 是您在 OpenAPI 规范的 host 字段中指定的值。对于 gRPC，ENDPOINTS_SERVICE_NAME 是您在 gRPC Endpoints 配置的 name 字段中指定的值。

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

如果您收到错误消息，请参阅排查 Endpoints 配置部署问题。

如需了解更多信息，请参阅部署 Endpoints 配置。

部署 API 后端

目前，您已将服务配置部署到 Service Management，但尚未部署将提供 API 后端的代码。本部分介绍了如何创建 GKE 集群以托管 API 后端，以及如何部署 API。

创建容器集群

集群需要 IP 别名才能使用容器原生负载平衡。为示例创建具有 IP 别名的容器集群：

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

上面的命令会在可用区 us-central1-a 中创建一个具有自动预配子网的集群 espv2-demo-cluster。

将 `kubectl` 向容器集群进行身份验证

要使用 kubectl 创建和管理集群资源，您需要获取集群凭据并将其提供给 kubectl。为此，请运行以下命令：将 NAME 替换为新的集群名称，将 ZONE 替换为其集群区域。

gcloud container clusters get-credentials NAME --zone ZONE

检查所需权限

ESP 和 ESPv2 会调用 Google 服务，这些服务使用 IAM 来验证调用身份是否具有足够的权限来访问使用的 IAM 资源。调用身份是部署 ESP 和 ESPv2 的关联服务账号。

部署在 GKE pod 中时，关联的服务账号是节点服务账号。它通常是 Compute Engine 默认服务账号。请按照此权限建议选择合适的节点服务账号。

如果使用 Workload Identity，则可以使用节点服务账号以外的其他服务账号来与 Google 服务通信。您可以为 pod 创建一个 Kubernetes 服务账号以运行 ESP 和 ESPv2，创建一个 Google 服务账号并将 Kubernetes 服务账号与该 Google 服务账号相关联。

按照这些步骤将 Kubernetes 服务账号与 Google 服务账号相关联。此 Google 服务账号是关联的服务账号。

如果关联的服务账号是项目的 Compute Engine 默认服务账号，并且端点服务配置部署在同一项目中，则服务账号应具有足够的权限来访问 IAM 资源，您可以跳过以下 IAM 角色设置步骤。否则，应将以下 IAM 角色添加到关联的服务账号。

添加所需的 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 代理启用 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是关联的服务账号。有关详情，请参阅什么是角色和权限？

配置 SSL 密钥和证书

容器原生负载平衡使用必须经过 TLS 加密的 HTTP2 LB。这需要将 TLS 证书部署到 GKE Ingress 和 ESPv2。您可以自带证书或使用自签名证书。

使用 openssl 创建自签名证书和密钥。在系统要求您提供“公用名 (CN)”时，请务必输入相同的 FQDN bookstore.endpoints.MY_PROJECT_ID.cloud.goog。客户端使用该名称来验证服务器证书。
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout ./server.key -out ./server.crt
```
使用您的 SSL 密钥和证书创建 Kubernetes Secret。请注意，证书会复制到两个位置，即 server.crt 和 tls.crt，因为密钥同时提供给 GKE Ingress 和 ESPv2。GKE Ingress 会查找证书路径 tls.crt，ESPv2 会查找证书路径 server.crt。
```
kubectl create secret generic esp-ssl \
--from-file=server.crt=./server.crt --from-file=server.key=./server.key \
--from-file=tls.crt=./server.crt --from-file=tls.key=./server.key
```

将示例 API 和 ESPv2 部署到集群

如需将示例 gRPC 服务部署到集群，以便客户端能够使用该服务，请执行以下操作：

git clone此代码库，并打开以修改 grpc-bookstore.yaml 部署清单文件。

将 SERVICE_NAME 替换为 Ingress 和 ESPv2 容器的 Endpoints 服务的名称。该名称与您在 name 字段中配置的名称相同位于 api_config.yaml 文件中。

# Copyright 2016 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

# Use this file to deploy the container for the grpc-bookstore sample
# and the container for the Extensible Service Proxy (ESP) to
# Google Kubernetes Engine (GKE).

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: esp-grpc-bookstore
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.allow-http: "false"
spec:
  tls:
  - hosts:
    - SERVICE_NAME
    secretName: esp-ssl
  backend:
    serviceName: esp-grpc-bookstore
    servicePort: 443
---
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: esp-grpc-bookstore
spec:
  healthCheck:
    type: HTTP2
    requestPath: /healthz
    port: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: esp-grpc-bookstore
  annotations:
    service.alpha.kubernetes.io/app-protocols: '{"esp-grpc-bookstore":"HTTP2"}'
    cloud.google.com/neg: '{"ingress": true, "exposed_ports": {"443":{}}}'
    cloud.google.com/backend-config: '{"default": "esp-grpc-bookstore"}'
spec:
  ports:
  # Port that accepts gRPC and JSON/HTTP2 requests over TLS.
  - port: 443
    targetPort: 9000
    protocol: TCP
    name: esp-grpc-bookstore
  selector:
    app: esp-grpc-bookstore
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: esp-grpc-bookstore
spec:
  replicas: 1
  selector:
    matchLabels:
      app: esp-grpc-bookstore
  template:
    metadata:
      labels:
        app: esp-grpc-bookstore
    spec:
      volumes:
      - name: esp-ssl
        secret:
          secretName: esp-ssl
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=SERVICE_NAME",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000",
          "--healthz=/healthz",
          "--ssl_server_cert_path=/etc/esp/ssl",
        ]
        ports:
          - containerPort: 9000
        volumeMounts:
        - mountPath: /etc/esp/ssl
          name:  esp-ssl
          readOnly: true
      - name: bookstore
        image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
        ports:
          - containerPort: 8000

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

例如：

    spec:
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=bookstore.endpoints.example-project-12345.cloud.goog",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]

如果您在同一 Google Cloud 项目中运行大型 Endpoints 组（超过 100 个），我们建议您装载服务容器配置，而不是使用 --rollout_strategy=managed 标志从 Service Management API 中拉取服务配置。Service Management API 具有默认的配额。如果大量 Endpoints 使用 --rollout_strategy=managed，则所有 Endpoints 都将轮询最新的服务配置。队列可能会超过配额，从而导致服务配置更新失败。请按照以下步骤装载服务配置。

下载服务配置 JSON 配置。

curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"

通过 JSON 配置创建 kubernetes 配置映射资源。

kubectl create configmap service-config-configmap \
  --from-file=service_config.json:/tmp/service_config.json

将 config map 资源装载到容器，并使用“--service_config_path”标记指定配置文件的路径。

例如：

  containers:
  - args:
    - --listener_port=8081
    - --backend=http://127.0.0.1:8080
    - --service_json_path=/etc/espv2_config/service_config.json
    - --healthz=/healthz
    image: gcr.io/endpoints-release/endpoints-runtime:2
    name: esp
    ports:
    - containerPort: 8081
      protocol: TCP
    volumeMounts:
    - mountPath: /etc/espv2_config
      name: service-config-volume
  volumes:
  - configMap:
      defaultMode: 420
      name: service-config-configmap
    name: service-config-volume

启动服务：
```
kubectl create -f grpc-bookstore.yaml
```

如果收到错误消息，请参阅对 GKE 中的 Endpoints 进行问题排查。

获取服务的外部 IP 地址

如需向示例 API 发送请求，您需要具备服务的外部 IP 地址。在容器中启动服务后，外部 IP 地址可能需要过几分钟才可以使用。

查看外部 IP 地址：
```
kubectl get ingress
```
记下 EXTERNAL-IP 的值并将其保存在 SERVER_IP 环境变量中。外部 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

为自签名证书创建根 CA

openssl x509 -in server.crt -out client.pem -outform PEM

向示例 API 发送一个请求：
```
python bookstore_client.py --host SERVER_IP --port 443 \
--servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
```
- 在 Endpoints > 服务页面中查看 API 的活动图表。
  
  转到“Endpoints 服务”页面
  
  请求可能需要一些时间才能体现在图表中。
- 在“日志浏览器”页面中查看 API 的请求日志。
  
  转到“日志浏览器”页面

如果未成功收到响应，请参阅排查响应错误。

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

清除数据

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除 API：
```
gcloud endpoints services delete SERVICE_NAME
```
将 SERVICE_NAME 替换为您的 API 名称。

删除 GKE 集群：

gcloud container clusters delete NAME --zone ZONE

后续步骤

了解如何为 Cloud Endpoints 配置您自己的 gRPC API。
仔细查看 GitHub 上的 Bookstore 示例。客户端和服务器均有 Python 版和 Java 版。
GitHub 上以下列语言提供了 getting-started-grpc 示例：
- Java
- Python
- Ruby
- Go
- Node.js

使用入门：GKE 上使用 ESPv2 的 Endpoints

目标

费用

准备工作

配置 Endpoints

部署 Endpoints 配置

检查所需服务

部署 API 后端

创建容器集群

将 kubectl 向容器集群进行身份验证

检查所需权限

添加所需的 IAM 角色：

端点服务配置

Cloud Trace

配置 SSL 密钥和证书

将示例 API 和 ESPv2 部署到集群

获取服务的外部 IP 地址

向 API 发送请求

清除数据

后续步骤

将 `kubectl` 向容器集群进行身份验证