迁移到 Extensible Service Proxy V2 Beta 版

Extensible Service Proxy V2 Beta 版(ESPv2 Beta 版)是一个基于 Envoy 的代理,通过该代理,Cloud Endpoints 可以提供 API 管理功能。 ESPV2 Beta 版替代了适用于 Cloud FunctionsCloud Run 的 Endpoints 初始 Beta 版随附的 Extensible Service Proxy (ESP)

本文档介绍了如何将现已部署的适用于 Cloud Functions 或 Cloud Run 的 Endpoints 从使用 ESP 迁移到使用 ESPv2 Beta 版。

本文档还介绍了在迁移 API 之前应注意的两个问题:

迁移 Endpoints API 以使用 ESPv2 Beta 版

要将 API 迁移到 ESPv2 Beta 版,只需将现有的 API 服务配置构建到新的 ESPv2 Beta 版 Docker 映像中,然后部署该映像。 要迁移 API,请参阅:

无需修改 API 规范或修改后端服务,除非您必须解决版本说明中描述的任何问题,或处理下述任何其他迁移问题。

更新用于指定启动选项的变量

要指定 ESP 的启动选项,您可以设置 ESP_ARGS 环境变量。

通过 ESPv2 Beta,您可以使用相同的机制设置启动选项,但环境变量现在命名为 ESPv2_ARGS。 请参阅 Extensible Service Proxy V2 Beta 版启动选项,详细了解如何设置 ESPv2_ARGS 以及设置 ESPv2_ARGS 时可用的选项。

处理后端服务中的 JWT

使用 JWT 执行身份验证时,ESP 通常会转发它收到的所有标头。但是,当 OpenAPI 规范中的 x-google-backend 或 gRPC 服务配置中的 BackendRule 指定了后端地址时,ESP 可能会覆盖原来的 Authorization 标头。 如果请求具有 Authorization 标头,并且 ESP 需要覆盖它,系统会将其值复制到新标头 X-Forwarded-Authorization

两个代理都会将 X-Endpoint-API-UserInfo 中的身份验证结果发送到后端 API。我们建议您使用此标头,而不是原来的 Authorization 标头。不过,标头的格式不同。

在 ESP 中,X-Endpoint-API-UserInfo 标头包含 Base64 编码的 JSON 对象,该对象包含 JWT 的载荷以及 ESP 添加的其他字段。

如果在 JWT 中可用,ESP 会将 idissueremailaudiences 属性添加到已编码的 JSON 对象中。它还会添加包含 JWT 原有载荷的 claims 属性。JSON 对象的形式如下:

{
      "id": "from-sub",
      "issuer": "from-iss",
      "email": "from-email",
      "audiences": ["from-aud"],
      "claims": {
         original-jwt-payload
       }
    }
    

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

ESPv2 Beta 版设置 X-Endpoint-API-UserInfo 标头的方式与 ESP 不同。 在 ESPv2 Beta 版中,X-Endpoint-API-UserInfo 标头仅包含未经修改的原始 JWT 的 Base64 编码载荷。

如果您的后端服务期望 X-Endpoint-API-UserInfo 标头使用 ESP 表示法,则必须更新服务以使用这种新格式。

后续步骤

了解以下内容: