Extensible Service Proxy V2 ベータ版への移行

Extensible Service Proxy V2 ベータ版(ESPv2 ベータ版)は、Cloud Endpoints で API 管理機能を提供できるようにする Envoy ベースのプロキシです。ESPv2 ベータ版は、Cloud FunctionsCloud Run 用に Endpoints の初期ベータ版リリースで出荷された Extensible Service Proxy(ESP)に代わるものです。

Cloud Functions または Cloud Run の Endpoints API の既存のデプロイにおいて、ESP の使用から、ESP v2 ベータ版の使用へ移行する方法について説明します。

このドキュメントでは、API を移行する前に考慮すべき次の 2 点についても説明します。

ESPv2 ベータ版を使用するための Endpoints API の移行

API を ESPv2 ベータ版に移行するには、既存の API サービス構成を新しい ESPv2 ベータ版の Docker イメージにビルドし、そのイメージをデプロイするだけです。API を移行するには、次のページをご覧ください。

リリースノートに記載されている問題を回避するか、下記の移行に関する問題に対処する場合を除き、API 仕様やバックエンド サービスを変更する必要はありません。

起動オプションの指定に使用される環境変数の更新

起動オプションを ESP に指定するには、ESP_ARGS 環境変数を設定します。

ESPv2 ベータ版では、同じ仕組みを使用して起動オプションを設定しますが、環境変数の名前は ESPv2_ARGS に変わります。ESPv2_ARGS の設定および、ESPv2_ARGS の設定で使用できるオプションについての詳細は、Extensible Service Proxy V2 ベータ版の起動オプションをご覧ください。

バックエンド サービスにおける 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 はエンコードされた JSON オブジェクトにidissueremailaudiences プロパティを追加します。また、JWT の元のペイロードを含む claims プロパティも追加します。この JSON オブジェクトは次のような形式です。

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

認証を含む JWT の使用についての詳細は、カスタム メソッドを使用したユーザーの認証サービス間の認証をご覧ください。

ESPv2 ベータ版では、X-Endpoint-API-UserInfo ヘッダーが ESP とは異なる形で設定されます。ESPv2 ベータ版を使用すると、X-Endpoint-API-UserInfo ヘッダーには元の JWT の Base64 でエンコードされたペイロードのみがそのまま含まれます。

バックエンド サービスが ESP 表現の X-Endpoint-API-UserInfo ヘッダーを前提としている場合は、この新しい形式を使用するようにサービスを更新する必要があります。

次のステップ

以下の内容について学習します。