迁移到 Extensible Service Proxy V2

Extensible Service Proxy V2 (ESPv2) 是一个基于 Envoy 的代理，通过该代理，Cloud Endpoints 可以提供 API 管理功能。ESPv2 取代了基于 NGINX 的 Extensible Service Proxy (ESP)。

本文档介绍如何将现有 Endpoints API 部署从 ESP 迁移到 ESPv2。

准备工作

在开始迁移之前，请考虑以下不受支持的用例和重大 API 更改。

ESPv2 不受支持的使用场景

• 不支持 App Engine 柔性环境

  App Engine 柔性环境具有内置的 Endpoints 支持，可通过在应用的 app.yaml 文件中设置 endpoints_api_service 来启用。此内置 Endpoints 实现仅支持 ESP；因此无法迁移到 ESPv2。

  如果要将 ESPv2 与 App Engine 柔性环境一起使用，请在 app.yaml 中停用 endpoints_api_service。您可以将 ESPv2 部署为单独的 Cloud Run 服务，用于在 App Engine 柔性环境中管理您的应用。部署的运作方式与 ESPv2 用于支持 App Engine 标准环境的方式相同。

• 不支持自定义 NGINX 配置

  ESPv2 是一种基于 Envoy 的代理。它无法支持自定义 NGINX 代理配置。如果您的 ESP 配置使用 -n 或 --nginx_config 标志，您的实现可能依赖于无法轻易迁移到 ESPv2 的自定义 NGINX 配置。

重大更改

• 更改了 X-Endpoint-API-UserInfo 标头数据格式。如果您的应用使用此标头，则必须将其改为使用新格式。如需了解详情，请参阅处理后端服务中的 JWT。

• 如果请求需要 API 密钥，ESP 将包含使用方项目 ID 的 X-Endpoint-API-Project-ID 标头发送给后端应用。ESPv2 使用两个不同的标头 X-Endpoint-API-Consumer-Type 和 X-Endpoint-API-Consumer-Number 发送所需的详细信息。如需详细了解通过这些标头发送的 Consumer-Type 和 Consumer-Number，请参阅 Service Infrastructure 参考文档。

• 更改了 HTTP 错误响应正文格式。当 ESPv2 拒绝 HTTP 请求时，它会以新的格式生成错误响应正文。如果您的实现使用客户端代码来处理 HTTP 错误 JSON 响应正文，则必须更新客户端代码。如需了解详情，请参阅 HTTP 错误 JSON 响应正文。

• ESPv2 中增加了新的启动标志，某些 ESP 标志已被弃用或替换。请参阅 ESP 和 ESPv2 之间的启动标志更改。

迁移 Endpoints API 以使用 ESPv2

将 ESPv2 与无服务器平台（Cloud Run、Cloud Run Functions、App Engine）搭配使用所需的迁移步骤与非无服务器平台（Google Kubernetes Engine、Compute Engine 和 Kubernetes）所需的步骤有所不同。

下文介绍了每种平台类型所需的迁移步骤：

非无服务器平台：GKE、Compute Engine、Kubernetes

ESPv2 可以直接替代 ESP。对于大多数配置，您只需更新到 Docker 映像标记。

但是，如果您的 ESP 配置了以下内容，则可能需要调整启动标志：

• 通过 --http_port、http2_port 和/或 --ssl_port 标志配置了多个端口。
• SSL、DNS、Client IP 或其他很少使用的标志。

ESPv2 使用新的启动标志，某些 ESP 标志已被弃用或替换。如需了解详情，请参阅 ESP 和 ESPv2 之间的启动标志更改。

GKE 和 Kubernetes

如需为 GKE 和 Kubernetes 迁移 Endpoints 配置，请在部署 yaml 文件中将 ESP 映像标记从 :1 更改为 :2。例如：

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--http_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed",
  ]

Compute Engine

ESP 和 ESPv2 都使用 docker run 命令部署到 Docker 容器。如需将 Compute Engine 的 Endpoints 迁移到 ESPv2，请将命令中的 Docker 映像标记从 :1 更新为 :2。例如：

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

无服务器平台（Cloud Run、Cloud Functions、App Engine）

对于无服务器平台，ESPv2 部署为 Cloud Run 服务，用于管理在 Cloud Run、Cloud Functions 或 App Engine 上运行的应用。要将 Endpoints 迁移到 ESPv2，您必须将现有 Endpoints 服务配置构建到新的 ESPv2 Docker 映像中，然后将映像部署到 ESPv2 Cloud Run 服务。

ESP 和 ESPv2 的部署步骤完全相同，但以下细节除外：

• 在将 ESPv2 部署到 Cloud Run 时，应在 ESPv2 中将映像标记从 :1 更改为 :2。例如：

  gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID  

• gcloud_build_image 脚本从不同的位置下载。它使用 gcr.io/endpoints-release/endpoints-runtime-serverless:2 作为基础映像。

• 环境变量用于指定启动标志。ESP 的变量名称为 ESP_ARGS。ESPv2 的名称为 ESPv2_ARGS。如需详细了解如何设置 ESPv2_ARGS 和可用的启动标志，请参阅 Extensible Service Proxy V2 启动选项。

ESP 和 ESPv2 之间的启动标志更改

与 Extensible Service Proxy 一样，您可以在部署 ESPv2 服务时指定配置标志。从基于 NGINX 的 ESP 更改为基于 Envoy 的 ESPv2 后，一些标志被弃用或替换，并添加了新标志。本部分使用三个表格来介绍这些更改：

• 表 1 介绍替换已弃用标志的新标志。
• 表 2 介绍新增标志。
• 表 3 介绍已弃用的标志。

被替换的标志

新增标志

已弃用的标志

如需详细了解 ESPv2 启动标志，请参阅 Extensible Service Proxy V2 启动选项。如需查看标志的更多一般示例和帮助文本，请访问 GitHub 代码库。

默认 JWT 位置

默认情况下，JWT 会在 Authorization 标头（以“Bearer”为前缀）、X-Goog-Iap-Jwt-Assertion 标头或 access_token 查询参数中传递。ESP 和 ESPv2 均支持这些位置。使用 ESP 时，您还可以在 Authorization 标头（不带前缀）中传递 JWT。但是，ESPv2 不支持此位置。

如果您希望在迁移到 ESPv2 后继续使用 Authorization 标头（不带前缀）传递 JWT，则可以执行以下操作：

• 在 openAPI 文件中设置 x-google-jwt-locations（适用于 HTTP 后端用户）：

x-google-jwt-locations:
- header: "Authorization"

• 在 gRPC yaml 文件中设置 Authentication.providers.jwt_locations（适用于 gRPC 后端用户）：

jwt_locations:
- header: Authorization

处理后端服务中的 JWT

使用 JWT 执行身份验证时，ESPv2 和 ESP 会向后端 API 发送 X-Endpoint-API-UserInfo 标头中的身份验证结果。我们建议您使用此标头，而不是原始 Authorization 标头，因为在无服务器平台中原始 Authorization 标头可能被修改。

X-Endpoint-API-UserInfo 标头包含一个 Base64Url 编码的 JSON 对象。不过，其格式已从 ESP 更改为 ESPv2。

对于 ESPv2，X-Endpoint-API-UserInfo 标头包含原始 JWT 载荷，无需进行任何修改。

在 ESP 中，X-Endpoint-API-UserInfo 标头包含 JWT 载荷以及 ESP 添加的一些特定字段。ESP 会将 id、issuer、email 和 audiences 字段添加到 JSON 对象。它还会添加 claims 字段以包含原始 JWT 载荷。

# ESPv1 X-Endpoint-API-UserInfo header value
{
  "id": "extracted from 'sub' field",
  "issuer": "extracted from 'iss' field",
  "email": "extracted from 'email' field",
  # The following "audiences" is extracted from 'aud' field.
  # The 'aud' field may have multiple audiences delimited by coma. e.g. "aud: aud1,aud2".
  # but the following "audiences" is always a JSON array.
  "audiences": ["aud1", "aud2"],
  "claims": {
     Original JWT payload
   }
}

以下示例说明了其中的差异，所有这些差异都经过了 base64url 解码。

# This is an example of the original JWT payload:
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2
# extracted from above JWT payload.
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESP
# extracted from above JWT payload.
{
  &quotid&quot:&quot1234567890123456789&quot,
  &quotissuer&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotaudiences&quot: [
    &quotxyz1.example.com&quot
    &quotxyz2.example.com&quot
  ],
  &quotclaims&quot: {
    &quotiss&quot: &quothttps://accounts.google.com&quot,
    &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
    &quotsub&quot: &quot1234567890123456789&quot,
    &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
    &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
    &quotbar&quot: &quotbar.bar.bar.bar&quot,
    &quotazp&quot: &quot98765432109876543210&quot,
    &quotexp&quot: &quot1642809446&quot,
    &quotiat&quot: &quot1642805846&quot
  }
}

请参阅使用自定义方法验证用户身份和服务之间的身份验证，详细了解如何使用 JWT 进行身份验证。

错误 JSON 响应正文格式

如果 ESP 或 ESPv2 拒绝 HTTP 请求，则响应正文将包含状态代码和 JSON 格式的错误消息。ESPv2 中的响应正文格式已更改，如以下示例所示：

ESP 的错误响应正文

{
 "code": 5,
 "message": "Method does not exist.",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "service_control"
  }
 ]
}

ESPv2 的错误响应正文

{
 "code": 400,
 "message": "Method does not exist.",
}

有两个主要区别：

• 在 ESPv2 中，code 字段包含 HTTP 状态代码，而不是 ESP 中的 RPC 状态代码。
• ESPv2 的错误响应正文不包含 details 字段。

后续步骤

了解：

• Extensible Service Proxy V2 启动选项
• OpenAPI 扩展程序
• GitHub 上的 ESPv2 代表库