ESPv2 を使用してスタンダード環境用の Cloud Endpoints OpenAPI を設定する

IAP を構成してアプリのセキュリティを確保する

App Engine アプリを保護するには、Identity Aware Proxy（IAP）を使用して、リクエストが認証されるようにする必要があります。

手順に従って IAP を有効化し、アプリにログインできることを確認します。

また、OAuth クライアントを構成するときに、OAuth client_id をメモしておきます。このチュートリアルでは、これを IAP_CLIENT_ID として記載します。

Cloud Run ホスト名の予約

OpenAPI ドキュメントまたは gRPC サービス構成を構成するには、ESPv2 サービス用の Cloud Run ホスト名を予約する必要があります。ホスト名を予約するには、Cloud Run にサンプル コンテナをデプロイします。後で、同じ Cloud Run サービスに ESPv2 コンテナをデプロイします。

1. gcloud CLI がデータやサービスにアクセスできるように承認されていることを確認します。
   1. ログインします。

      gcloud auth login

   2. 表示された新しいブラウザタブで、ESPv2 を Cloud Run にデプロイするために作成した Google Cloud プロジェクトの編集者またはオーナーのロールが割り当てられているアカウントを選択します。
2. リージョンを設定します。

   gcloud config set run/region us-central1

3. サンプル イメージ gcr.io/cloudrun/hello を Cloud Run にデプロイします。CLOUD_RUN_SERVICE_NAME は、このサービスに使用する名前に置き換えます。

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   このコマンドが正常に完了すると、次のようなメッセージが表示されます。

   Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   CLOUD_RUN_SERVICE_NAME を gateway に設定した場合:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   この例では、https://gateway-12345-uc.a.run.app が CLOUD_RUN_SERVICE_URL で、gateway-12345-uc.a.run.app が CLOUD_RUN_HOSTNAME です。

4. CLOUD_RUN_SERVICE_NAME と CLOUD_RUN_HOSTNAME をメモします。ESPv2 ベータ版を後で CLOUD_RUN_SERVICE_NAME Cloud Run サービスにデプロイします。OpenAPI ドキュメントの host フィールドで CLOUD_RUN_HOSTNAME を指定します。

Endpoints を構成する

OpenAPI 仕様 v2.0 に基づいて、アプリの surface と認証要件を記述する OpenAPI ドキュメントを用意する必要があります。また、ESPv2 がアプリを呼び出すために必要な情報を取得できるよう、このドキュメントには各アプリの URL を設定した Google 固有のフィールドも追加する必要があります。OpenAPI を初めて使用する場合は、OpenAPI の概要で詳細をご覧ください。

1. openapi-appengine.yaml という名前のテキスト ファイルを作成します（便宜上、このページでは OpenAPI ドキュメントをこのファイル名で表記していますが、必要に応じて別の名前を指定することもできます）。
2. App Engine バックエンドアプリは、openapi-appengine.yamlファイルの先頭にあるx-google-backend定義で定義されます。次に例を示します。

     swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: CLOUD_RUN_HOSTNAME
     schemes:
       - https
     produces:
       - application/json
     x-google-backend:
       address: https://APP_PROJECT_ID.REGION.r.appspot.com
       jwt_audience: IAP_CLIENT_ID
       protocol: h2
     paths:
       /:
         get:
           summary: Greet a user
           operationId: hello
           responses:
             '200':
               description: A successful response
               schema:
                 type: string

   yaml 形式ではインデントが重要です。たとえば、host フィールドは info と同じレベルにする必要があります。
3. x-google-backend セクションの address フィールドで、APP_PROJECT_ID を Google Cloud プロジェクト ID、REGION を App Engine をデプロイした GCP リージョン、IAP_CLIENT_ID を IAP の設定時に作成した OAuth クライアント ID に置き換えます。

4. host フィールドで、CLOUD_RUN_HOSTNAME を指定します。これは、Cloud Run ホスト名の予約で予約した URL のホスト名の部分です。プロトコルの識別子である https:// は含めません。次に例を示します。

   swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: gateway-12345-uc.a.run.app

5. openapi-appengine.yaml ファイルの title プロパティの値をメモします。

   title: Cloud Endpoints + App Engine

   title プロパティの値は、構成をデプロイした後の Endpoints サービスの名前になります。

6. OpenAPI ドキュメントを保存します。

Endpoints に必要な OpenAPI ドキュメントのフィールドについては、Endpoints を構成するをご覧ください。

Endpoints 構成をデプロイする

Endpoints の構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージド サービスが作成されます。

Endpoints 構成をデプロイするには:

1. OpenAPI ドキュメントが格納されているディレクトリに移動します。

2. 構成をアップロードしてマネージド サービスを作成します。

   gcloud endpoints services deploy openapi-appengine.yaml \
     --project ESP_PROJECT_ID

   これにより、openapi-appengine.yaml ファイルの host フィールドに指定した名前で、新しい Endpoints サービスが作成されます。このサービスは、OpenAPI ドキュメントに従って構成されています。

   Service Management でサービスの作成と構成が行われるとき、情報がデバイスに出力されます。デプロイが完了すると、次のようなメッセージが表示されます。

   Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

   CONFIG_ID は、デプロイによって作成される一意の Endpoints サービス構成 ID です。次に例を示します。

   Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

   サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi-appengine.yaml を再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Google Cloud コンソールで [エンドポイント] > [サービス] ページを開くと、サービス構成とデプロイの履歴を確認できます。

   エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

必要なサービスの確認

ほとんどの場合、gcloud endpoints services deploy コマンドによってこれらの必須サービスが有効化されます。ただし、以下の状況では、gcloud コマンドは正常に完了しますが、必須サービスが有効になりません。

• Terraform などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。

• 上記のサービスが明示的に無効にされている既存の Google Cloud プロジェクトに Endpoints 構成をデプロイした場合。

必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list

必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.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 サービスをご覧ください。

新しい ESPv2 イメージをビルドする

新しい ESPv2 Docker イメージに Endpoints サービス構成をビルドします。その後、このイメージを予約済みの Cloud Run サービスにデプロイします。

新しい ESPv2 Docker イメージにサービス構成をビルドするには:

1. gcloud CLI がインストールされているローカルマシンにこのスクリプトをダウンロードします。

2. 次のコマンドでスクリプトを実行します。

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   CLOUD_RUN_HOSTNAME には、Cloud Run ホスト名の予約で予約した URL のホスト名を指定します。プロトコルの識別子である https:// は含めません。

   次に例を示します。

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. このスクリプトは、gcloud コマンドを使用してサービス構成をダウンロードし、新しい ESPv2 イメージにサービス構成をビルドして、新しいイメージを次のプロジェクト コンテナ レジストリにアップロードします。このスクリプトは、出力イメージ名に ESP_VERSION で示される ESPv2 の最新リリースを自動的に使用します。出力イメージは次の場所にアップロードされます。

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

   次に例を示します。

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

ESPv2 コンテナをデプロイする

1. 前の手順で作成した新しいイメージを使用して、ESPv2 Cloud Run サービスをデプロイします。CLOUD_RUN_SERVICE_NAME は、Cloud Run ホスト名の予約で、前の手順でホスト名を予約したときと同じ Cloud Run サービスの名前に置き換えます。

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

2. CORS を有効にするなどの追加の ESPv2 起動オプションを使用するように Endpoints を構成する場合は、引数を ESPv2_ARGS 環境変数に渡すことができます。

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESP_PROJECT_ID

   使用可能なオプションのリスト、複数のオプションの指定方法についての情報など、ESPv2_ARGS 環境変数の詳細と設定例については、Extensible Service Proxy V2 のフラグをご覧ください。

3. IAP で保護されたアプリを呼び出す権限を ESPv2 に付与します。各サービスに対して次のコマンドを実行します。このコマンドで、次の要素を置き換えてください。
   • APP_PROJECT_ID を App Engine のプロジェクト ID に置き換えます。
   • ESP_PROJECT_NUMBER は、ESPv2 に作成したプロジェクトのプロジェクト番号に置き換えます。この番号を調べる 1 つの方法としては、IAM コンソールに移動して、Compute Engine のデフォルトのサービス アカウントを探す方法があります。これは、member フラグで使用されているサービス アカウントです。

     gcloud projects add-iam-policy-binding APP_PROJECT_ID \
         --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
         --role "roles/iap.httpsResourceAccessor"
       

詳しくは、IAM を使用したアクセスの管理をご覧ください。

API にリクエストを送信する

このセクションでは、API にリクエストを送信する方法を説明します。

1. Endpoints サービス名の環境変数を作成します。これは、OpenAPI ドキュメントの host フィールドで指定した名前です。例:

   • Linux または macOS:

     export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

   • Windows PowerShell:

     $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/"

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/").Content

正常なレスポンスが返されなかった場合は、レスポンス エラーのトラブルシューティングをご覧ください。

これで Endpoints の API のデプロイとテストが完了しました。

API の活動を追跡する

1. Google Cloud コンソールで [Endpoints] > [サービス] ページに移動して、API のアクティビティ グラフを表示します。

   Endpoints のアクティビティ グラフを表示

   グラフにリクエストが反映されるまでしばらくかかります。

2. [ログ エクスプローラ] ページで、API のリクエストログを確認します。

   Endpoints のリクエストログを表示

API のデベロッパー ポータルを作成する

Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。