使用入门:GKE 上使用 ESPv2 的 Cloud Endpoints

本教程介绍如何配置示例 API 和 Extensible Service Proxy V2 Beta 版(ESPv2 Beta 版),并将其部署到 Google Kubernetes Engine (GKE) 集群。

该示例代码的 REST API 使用 OpenAPI 规范进行描述。本教程还介绍了如何创建 API 密钥,以及如何在向 API 发送请求时使用此密钥。

本教程使用了示例代码和 ESPv2 Beta 版的预构建容器映像,这些映像存储在 Container Registry 中。

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

目标

学习本教程时,请使用以下概要任务列表。为了向 API 成功发送请求,您必须完成第 1 部分中的所有任务。

第 1 部分

  1. 设置 Google Cloud 项目。请参阅准备工作
  2. 在 GKE 上创建容器集群。请参阅创建容器集群
  3. 安装并配置本教程中使用的软件。请参阅安装和配置所需的软件
  4. 下载示例代码。请参阅获取示例代码
  5. 配置 openapi.yaml 文件,该文件用于配置 Cloud Endpoints。请参阅配置 Endpoints
  6. 部署 Endpoints 配置以创建 Endpoints 服务。请参阅部署 Endpoints 配置
  7. 将 API 和 ESPv2 Beta 版部署到集群。请参阅部署 API 后端
  8. 获取集群的 IP 地址。请参阅获取集群的外部 IP 地址
  9. 使用 IP 地址向 API 发送请求。请参阅使用 IP 地址发送请求
  10. 跟踪 API 活动。请参阅跟踪 API 活动

第 2 部分

  1. 为示例 API 配置 DNS 记录。请参阅为 Endpoints 配置 DNS
  2. 使用完全限定的域名向 API 发送请求。请参阅使用 FQDN 发送请求

清理

完成后,请参阅清理,以避免您的 Google Cloud 帐号产生费用。

费用

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

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

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

准备工作

  1. 登录您的 Google 帐号。

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

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

    转到项目选择器页面

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

  4. 记下 Google Cloud 项目 ID,因为以后需要它。

创建容器集群

您必须在 GKE 上创建一个容器集群,以便在其中运行示例 API 后端代码。 如需为示例 API 创建容器集群,请执行以下操作:

  1. 在 Google Cloud Console 中,转到“GKE 集群”页面。

    转到“Kubernetes 集群”页面

  2. 点击创建集群
  3. 接受默认值,然后点击创建。此步骤可能需要几分钟时间才能完成。
  4. 请记下集群名称和地区,因为在向容器集群进行 kubectl 身份验证时需要用到。

安装和配置所需的软件

在本教程中,需安装 Cloud SDK,以便可使用 gcloud 命令行界面管理项目。您可以使用 kubectl 对 GKE 集群运行命令。您还需要一种用于测试 API 的方法。

在以下过程中,如果您已安装所需的软件,请继续执行后续步骤。

如需安装和配置所需的软件,请执行以下操作:

  1. 您需要一个可以向示例 API 发送请求的应用。

    • Linux 和 macOS 用户:本教程提供了一个使用 curl 的示例,它通常已预装在您的操作系统中。如果您没有 curl,可以从 curl 版本和下载页面中下载。
    • Windows 用户:本教程提供了一个使用 Invoke-WebRequest 的示例,PowerShell 3.0 及更高版本支持该命令。
  2. 安装并初始化 Cloud SDK
  3. 更新 Cloud SDK 并安装 Endpoints 组件:
    gcloud components update
  4. 确保 Cloud SDK (gcloud) 有权访问您在 Google Cloud 上的数据和服务:
    gcloud auth login
    在浏览器打开的新标签页中,选择一个帐号。
  5. 将默认项目设置为您的项目 ID:
    gcloud config set project YOUR_PROJECT_ID

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

  6. 安装 kubectl
    gcloud components install kubectl
  7. 获取用于应用默认凭据的新用户凭据。在向 kubectl 授权时,需要该用户凭据。
    gcloud auth application-default login
    在浏览器打开的新标签页中,选择一个帐号。

下载示例代码

为了帮助您快速上手,本教程提供了多种语言的示例代码。 如需将示例代码下载到本地机器,请执行以下操作:

Java

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用存储库克隆到您的本地机器:
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd java-docs-samples/endpoints/getting-started
Python

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用存储库克隆到您的本地机器:
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd python-docs-samples/endpoints/getting-started
Go

如需克隆或下载示例 API,请执行以下操作:

  1. 确保已设置 GOPATH 环境变量
  2. 将示例应用代码库克隆到本地机器:
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. 转到包含示例代码的目录:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用存储库克隆到您的本地机器:
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd php-docs-samples/endpoints/getting-started
Ruby

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用存储库克隆到您的本地机器:
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 转到包含示例代码的目录:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

如需克隆或下载示例 API,请执行以下操作:

  1. 将示例应用存储库克隆到您的本地机器:
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    或者,下载该示例的 zip 文件并将其解压缩。

  2. 切换到包含示例代码的目录:
    cd nodejs-docs-samples/endpoints/getting-started

配置 Endpoints

示例代码包括 OpenAPI 配置文件 openapi.yaml,该文件基于 OpenAPI 规范 v2.0。要配置 Endpoints,请执行以下操作:

  1. 在示例代码目录中,打开 openapi.yaml 配置文件。

    请注意以下事项:

    • 配置示例显示了 host 字段附近的几行内容,您需要修改这些内容。如需将 openapi.yaml 文件部署到 Endpoints,您需要完整的 OpenAPI 文档。
    • 示例 openapi.yaml 文件包含用于配置身份验证的部分(本教程不需要)。您无需使用 YOUR-SERVICE-ACCOUNT-EMAILYOUR-CLIENT-ID 配置这些行。
    • OpenAPI 是一种与语言无关的规范。为方便起见,每种语言的 GitHub 存储库中的 getting-started 示例均包含相同的 openapi.yaml 文件。
  2. host 字段中的文本替换为 Endpoints 服务名称,该名称应采用以下格式:
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    

    YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如:

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    

请注意,echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog 是 Endpoints 服务名称。该名称不是您用于向 API 发送请求的完全限定域名 (FQDN)。

要了解 OpenAPI 文档中 Endpoints 所需的字段,请参阅配置 Endpoints

为了能够使用 IP 地址向示例 API 成功发送请求,您需要完成以下所有配置步骤。在完成这些步骤后,请参阅配置 Endpoints DNS,了解如何将 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog 配置为 FQDN。

部署 Endpoints 配置

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

如需部署 Endpoints 配置,请执行以下操作:

  1. 确保您位于 endpoints/getting-started 目录中。
  2. 上传配置并创建托管式服务:
    gcloud endpoints services deploy openapi.yaml
    

然后,gcloud 命令会调用 Service Management API,以便使用您在 openapi.yaml 文件的 host 字段中指定的名称创建托管式服务。Service Management 会根据 openapi.yaml 文件中的设置来配置服务。如果您对 openapi.yaml 做出更改,则必须重新部署该文件才能更新 Endpoints 服务。

在创建和配置服务时,Service Management 会向终端输出信息。您尽可忽略有关 openapi.yaml 文件中的路径未要求使用 API 密钥的警告。完成服务配置后,Service Management 将显示如下所示的消息,其中包含服务配置 ID 和服务名称:

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

在上面的示例中,2017-02-13r0 是服务配置 ID,echo-api.endpoints.example-project-12345.cloud.goog 是 Endpoints 服务。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 openapi.yaml 文件,服务配置 ID 中的修订版本号将递增。您可以在 Cloud Console 中的 Endpoints > 服务页面上查看 Endpoints 服务配置。

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

检查所需服务

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 服务

部署 API 后端

到目前为止,您已将 OpenAPI 文档部署到 Service Management,但尚未部署为 API 后端提供服务的代码。本部分逐步介绍如何将示例 API 和 ESPv2 Beta 版的预构建容器部署到容器。

检查所需权限

请按照此权限建议选择合适的节点服务帐号,作为与 Google 服务通信的身份。ESP 和 ESPv2 Beta 版需要与 Google ServiceController 和 Stackdriver 通信,但运行 ESP 和 ESPv2 Beta 版的节点服务帐号需要其他 IAM 角色。

如果节点服务帐号不是 Compute Engine 默认服务帐号,请按照下一步添加所需的 IAM 角色:

添加所需的 IAM 角色:

用于 ESP 和 ESPv2 Beta 版的服务帐号需要以下 IAM 角色。

如需将 Service Controller 和 Cloud Trace Agent IAM 角色添加到服务帐号,请执行以下操作:

控制台

  1. 在 Cloud Console 中,选择您在其中创建了服务帐号的项目。
  2. 打开 IAM/Iam 页面

    转到“IAM/Iam”页面

    。该页面应该列出所有 IAM 成员,包括所有服务帐号。
  3. 选择您的服务帐号,然后点击右侧的修改图钉。
  4. 此时将打开修改权限面板。
  5. 点击 + 添加其他角色
  6. 点击选择角色,然后选择 Service Management > Service Controller
  7. 点击 + 添加其他角色
  8. 点击选择角色,然后选择 Cloud Trace > Cloud Trace Agent
  9. 点击保存
  10. 现在,您可以在 IAM 页面上服务帐号的角色列中查看 Service ControllerCloud Trace Agent 角色。

gcloud

  1. 添加 Service Controller 角色:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. 添加 Cloud Trace Agent 角色以启用 Cloud Trace:

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/cloudtrace.agent

如需了解详情,请参阅什么是角色和权限?

Workload Identity:

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

按照这些步骤将 Kubernetes 服务帐号与 Google 服务帐号相关联。

Google 服务帐号应具有所需的 IAM 角色。如果没有,请按照添加所需的 IAM 角色步骤操作。

将容器部署到集群

容器提供了一种逻辑打包机制,让您能够使应用脱离其实际运行的环境。您可按以下流程将示例 API 和 ESPv2 Beta 版部署到集群。如需将容器部署到集群,请执行以下操作:

  1. 获取集群凭据并将其提供给 kubectl
        gcloud container clusters get-credentials NAME --zone ZONE
        
    NAME 替换为集群名称,将 ZONE 替换为集群地区。
  2. 将 Kubernetes 服务部署到 GKE 集群。Kubernetes 服务可实现 API。git clone代码库cd getting-started/至文件夹并修改 Kubernetes 配置文件 LANG-deployment.yaml,并将 ESPv2 Beta 版启动选项中的 SERVICE_NAME 替换为您的服务名称。

    例如:

      args: [
        "--listener_port=8081",
        "--backend=http://127.0.0.1:8080",
        "--service=echo-api.endpoints.example-project-12345.cloud.goog ",
        "--rollout_strategy=managed",
      ]
    

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

  3. 使用 kubectl apply 命令启动 Kubernetes 服务:

    Java
    kubectl apply -f java-deployment.yaml
    Python
    kubectl apply -f python-deployment.yaml
    Go
    kubectl apply -f golang-deployment.yaml
    PHP
    kubectl apply -f php-deployment.yaml
    Ruby
    kubectl apply -f ruby-deployment.yaml
    NodeJS
    kubectl apply -f nodejs-deployment.yaml

如果收到错误消息,请参阅排查 GKE 中的 Endpoints 问题。 如需了解详情,请参阅部署 API 后端

获取集群的外部 IP 地址

为了向 API 发送请求,您需要该服务的外部 IP 地址。在容器中启动服务后,外部 IP 地址可能需要过几分钟才可以使用。

  1. 查看外部 IP 地址:kubectl get service
  2. 请记下 EXTERNAL-IP 的值。在向示例 API 发送请求时,您需要使用该 IP 地址。

使用 IP 地址发送请求

服务正在容器集群中运行,而且您已具备外部 IP 地址,接下来就可向 API 发送请求了。

创建 API 密钥并设置环境变量

示例代码需要 API 密钥。为简化请求,请为 API 密钥设置环境变量。

  1. 在您用于 API 的同一 Google Cloud 项目中,在 API 凭据页面上创建 API 密钥。如果要在其他 Google Cloud 项目中创建 API 密钥,请参阅在 Google Cloud 项目中启用 API

    转到“凭据”页面

  2. 点击创建凭据,然后选择 API 密钥
  3. 将密钥复制到剪贴板。
  4. 点击关闭
  5. 在本地计算机上,粘贴 API 密钥以将其分配给环境变量:
    • 在 Linux 或 macOS 中:export ENDPOINTS_KEY=AIza...
    • 在 Windows PowerShell 中:$Env:ENDPOINTS_KEY="AIza..."

发送请求

Linux 或 macOS

通过 curl 使用之前设置的 ENDPOINTS_KEY 环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

在上面的 curl 中:

  • --data 选项用于指定要发布到 API 的数据。
  • --header 选项用于指定数据采用 JSON 格式。

PowerShell

通过 Invoke-WebRequest 使用之前设置的 ENDPOINTS_KEY 环境变量发送 HTTP 请求。将 IP_ADDRESS 替换为实例的外部 IP 地址。

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

在上面的示例中,前两行以反引号结束。将示例粘贴到 PowerShell 中时,请确保反引号后面没有空格。 如需了解示例请求中使用的选项,请参阅 Microsoft 文档中的 Invoke-WebRequest

第三方应用

您可以使用第三方应用(如 Chrome 浏览器扩展程序 Postman)发送请求:

  • 选择 POST 作为 HTTP 谓词。
  • 对于标头,请选择键 content-type 和值 application/json
  • 对于正文,请输入以下内容:
    {"message":"hello world"}
  • 在网址中,使用实际的 API 密钥,而非环境变量。例如:
    http://192.0.2.0:80/echo?key=AIza...

API 会回显您发送的消息,并以如下内容作为响应:

{
  "message": "hello world"
}

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

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

跟踪 API 活动

要跟踪 API 活动,请执行以下操作:

  1. Endpoints > 服务页面中查看 API 的活动图表。

    转到“Endpoints 服务”页面


    请求可能需要一些时间才能体现在图表中。
  2. 在“日志查看器”页面中查看 API 的请求日志。

    转到“日志查看器”页面

为 Endpoints 配置 DNS

由于 API 的 Endpoints 服务名称在 .endpoints.YOUR_PROJECT_ID.cloud.goog 域名中,因此您在 openapi.yaml 文件中稍微更改一下配置,即可将该名称用作完全限定的域名 (FQDN)。这样,您就可使用 echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog(而非 IP 地址)向示例 API 发送请求。

如需配置 Endpoints DNS,请执行以下操作:

  1. 打开 OpenAPI 配置文件 openapi.yaml,并在该文件的顶层添加 x-google-endpoints 属性(请勿使用缩进或嵌套结构),如以下代码段所示:
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
      target: "IP_ADDRESS"
    
  2. name 属性中,将 YOUR_PROJECT_ID 替换为您的项目 ID。
  3. target 属性中,将 IP_ADDRESS 替换为您向示例 API 发送请求时使用的 IP 地址。
  4. 将更新后的 OpenAPI 配置文件部署到 Service Management:
    gcloud endpoints services deploy openapi.yaml
    

例如,假设 openapi.yaml 文件进行了以下配置:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

使用上述 gcloud 命令部署 openapi.yaml 文件时,Service Management 会创建一条 DNS A 记录 echo-api.endpoints.my-project-id.cloud.goog,该记录将解析为目标 IP 地址 192.0.2.1。新 DNS 配置可能需要几分钟的时间才能传播。

配置 SSL

如需详细了解如何配置 DNS 和 SSL,请参阅为 Endpoints 启用 SSL

使用 FQDN 发送请求

在为示例 API 配置 DNS 记录后,请使用 FQDN(将 YOUR_PROJECT_ID 替换为您的项目 ID)和先前设置的 ENDPOINTS_KEY 环境变量向该 API 发送请求:
  • 在 Linux 或 Mac OS 中:
    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • 在 Windows PowerShell 中:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

为 API 创建开发者门户

可使用 Cloud Endpoints 门户创建开发者门户,该门户是一个可用于与示例 API 进行交互的网站。如需了解详情,请参阅 Cloud Endpoints 门户概览

清理

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

如需了解如何停止本教程使用的服务,请参阅删除 API 和 API 实例

后续步骤