ESPv2 を使用して Cloud Run 用の Cloud Endpoints gRPC を設定する
このページでは、gRPC バックエンドで Cloud Run 用に Cloud Endpoints を設定する方法について説明します。 Endpoints は Extensible Service Proxy V2（ESPv2）を API ゲートウェイとして使用します。Cloud Run 向けに API 管理機能を提供するには、事前にビルドされた ESPv2 コンテナを Cloud Run にデプロイします。Cloud Run IAM を使用してサービスを保護し、ESPv2 版がサービスを呼び出せるようにします。
この設定では、ESPv2 がサービスに対するすべてのリクエストを傍受し、必要なチェック（認証など）を行ってから、該当するサービスを呼び出します。サービスが応答すると、ESPv2 は次の図に示すようにテレメトリーを収集して報告します。サービスの指標は、Google Cloud Console の [エンドポイント] > [サービス] ページで確認できます。
Cloud Endpoints の概要については、Endpoints についてと Endpoints アーキテクチャをご覧ください。
ESPv2 に移行する
Cloud Endpoints の以前のリリースでは、ESP を使用した Cloud Run で gRPC がサポートされていませんでした。この機能を使用するには、Extensible Service Proxy V2 に移行してください。
タスクリスト
次のタスクリストを参照しながら、チュートリアルを実施してください。このチュートリアルを完了するには、すべてのタスクを行う必要があります。
- Google Cloud プロジェクトを作成します。独自の Cloud Run をデプロイしていない場合は、サンプルのバックエンド gRPC サービスをデプロイします。始める前にをご覧ください。
- ESPv2 サービス用に Cloud Run のホスト名を予約します。Cloud Run ホスト名の予約をご覧ください。
- API を記述する gRPC API 構成ドキュメントを作成し、Cloud Run へのルートを構成します。 Endpoints を構成するをご覧ください。
- gRPC API 構成ドキュメントをデプロイしてマネージド サービスを作成します。 Endpoints 構成をデプロイするをご覧ください。
- Endpoints サービス構成で新しい ESPv2 Docker イメージをビルドします。新しい ESPv2 イメージをビルドするをご覧ください。
- ESPv2 コンテナを Cloud Run にデプロイします。次に、サービスを呼び出すための Identity and Access Management（IAM）権限を ESPv2 に付与します。ESPv2 コンテナをデプロイするをご覧ください。
- サービスを呼び出します。API にリクエストを送信するをご覧ください。
- サービスに対するアクティビティを追跡します。API の活動を追跡するをご覧ください。
- Google Cloud アカウントへの課金が発生しないようにします。クリーンアップをご覧ください。
費用
このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。
始める前に
次の手順に従って設定します。
Google Cloud コンソールで [リソースの管理] ページに移動し、プロジェクトを作成します。
プロジェクトに対して課金が有効になっていることを確認します。
後で必要になるため、プロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を ESP_PROJECT_ID として記載します。
後で必要になるため、プロジェクト番号をメモしておきます。このページでは以降、このプロジェクト番号を ESP_PROJECT_NUMBER として記載します。
Google Cloud CLI をダウンロードしてインストールします。
gRPC Python クイックスタートの手順に従い、gRPC と gRPC ツールをインストールします。
このチュートリアルで使用する Python-grpc-bookstore-serverのサンプル バックエンド gRPC Cloud Run サービスをデプロイします。gRPC サービスは次のコンテナ イメージを使用します。
gcr.io/endpointsv2/python-grpc-bookstore-server:2クイックスタート: 事前にビルドされたサンプル コンテナをデプロイするの手順に従って、サービスをデプロイします。
gcr.io/endpointsv2/python-grpc-bookstore-server:2でクイックスタートで指定されているコンテナイメージを置き換えます。サービスがデプロイされているリージョンとプロジェクト ID をメモしておきます。このページでは以降、このプロジェクト ID を BACKEND_PROJECT_ID として記載します。デプロイされた Cloud Run サービスの名前は BACKEND_SERVICE_NAME とします。Cloud Run のホスト名は BACKEND_HOST_NAME とします。
Cloud Run ホスト名の予約
OpenAPI ドキュメントまたは gRPC サービス構成を構成するには、ESPv2 サービス用の Cloud Run ホスト名を予約する必要があります。ホスト名を予約するには、Cloud Run にサンプル コンテナをデプロイします。後で、同じ Cloud Run サービスに ESPv2 コンテナをデプロイします。
-
gcloud CLI がデータやサービスにアクセスできるように承認されていることを確認します。
- ログインします。
gcloud auth login
- 表示された新しいブラウザタブで、ESPv2 を Cloud Run にデプロイするために作成した Google Cloud プロジェクトの編集者またはオーナーのロールが割り当てられているアカウントを選択します。
- ログインします。
- リージョンを設定します。
gcloud config set run/region us-central1
-
サンプル イメージ
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 です。 - CLOUD_RUN_SERVICE_NAME と CLOUD_RUN_HOSTNAME をメモします。ESPv2 ベータ版を後で CLOUD_RUN_SERVICE_NAME Cloud Run サービスにデプロイします。OpenAPI ドキュメントの
hostフィールドで CLOUD_RUN_HOSTNAME を指定します。
Endpoints の設定
bookstore-grpc サンプルには、ローカルにコピーして構成する必要のあるファイルが含まれています。
- サービスの
.protoファイルから、自己完結型 protobuf 記述子ファイルを作成します。- サンプル リポジトリから現在の作業ディレクトリに
bookstore.protoのコピーを保存します。このファイルは Bookstore サービスの API を定義します。 - 作業ディレクトリの下に次のディレクトリを作成します。
mkdir generated_pb2 protocプロトコル バッファ コンパイラを使用して、記述子ファイルapi_descriptor.pbを作成します。bookstore.protoを保存したディレクトリで次のコマンドを実行します。python3 -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto上記のコマンドでは、
--proto_pathが現在の作業ディレクトリに設定されています。gRPC ビルド環境で、.proto入力ファイルに別のディレクトリを使用する場合は、bookstore.protoを保存したディレクトリをコンパイラが検索するように--proto_pathを変更します。
- サンプル リポジトリから現在の作業ディレクトリに
-
現在の作業ディレクトリ（
bookstore.protoを含む同じディレクトリ）にapi_config.yamlという名前のテキスト ファイルを作成します。便宜上、このページでは gRPC API 構成ドキュメントをそのファイル名で表記していますが、必要に応じて別の名前を指定することもできます。ファイルに次の内容を追加します。# The configuration schema is defined by the service.proto file. # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto type: google.api.Service config_version: 3 name: CLOUD_RUN_HOSTNAME title: Cloud Endpoints + Cloud Run gRPC apis: - name: endpoints.examples.bookstore.Bookstore usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true backend: rules: - selector: "*" address: grpcs://BACKEND_HOST_NAMEyaml 形式ではインデントが重要です。たとえば、nameフィールドはtypeと同じレベルにする必要があります。 nameフィールドで、CLOUD_RUN_HOSTNAME を指定します。これは、Cloud Run ホスト名の予約で予約した URL のホスト名の部分です。プロトコル識別子（https://やgrpcs://など）は含めないでください。backend.rulesセクションのaddressフィールドで、BACKEND_HOST_NAME は、始める前にで作成した実際の gRPC Bookstore Cloud Run サービスに置き換えます。api_config.yamlファイルのtitleプロパティの値をメモします。title: Cloud Endpoints + Cloud Run gRPC
titleプロパティの値は、構成をデプロイした後の Endpoints サービスの名前になります。- gRPC API 構成ドキュメントを保存します。
詳細については、Endpoints を構成するをご覧ください。
Endpoints 構成をデプロイする
Endpoints の構成をデプロイするには、gcloud endpoints services deploy コマンドを使用します。このコマンドを実行すると、Service Management を使用してマネージド サービスが作成されます。
api_descriptor.pbファイルとapi_config.yamlファイルがあるディレクトリにいることを確認します。gcloudコマンドライン ツールが現在使用しているデフォルト プロジェクトが、エンドポイント構成をデプロイする Google Cloud プロジェクトであることを確認します。それには、次のコマンドを使用して返されるプロジェクト ID を確認してください。これは、間違ったプロジェクト内にサービスが作成されないようにするためです。gcloud config list project
デフォルト プロジェクトを変更する必要がある場合は、次のコマンドを実行します。
gcloud config set project YOUR_PROJECT_ID
- Google Cloud CLI を使用して、
proto descriptorファイルと構成ファイルをデプロイします。gcloud endpoints services deploy api_descriptor.pb api_config.yaml
サービスが作成され構成されるに従い、ターミナルには Service Management からの情報が出力されます。デプロイが完了すると、次のようなメッセージが表示されます。
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID は、デプロイによって作成される一意の Endpoints サービス構成 ID です。例:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
上記の例では、
2017-02-13r0はサービス構成 ID で、bookstore.endpoints.example-project.cloud.googはサービス名です。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。Endpoints の構成を同じ日に再デプロイすると、サービス構成 ID のリビジョン番号が増分されます。
必要なサービスの確認
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 などのサードパーティのアプリケーションを使用していて、上記のサービスを含めていない場合。
上記のサービスが明示的に無効にされている既存の Google Cloud プロジェクトに Endpoints 構成をデプロイした場合。
必要なサービスが有効になっていることを確認するには、次のコマンドを実行します。
gcloud services list
必要なサービスが表示されない場合は、次のコマンドを使用してサービスを有効にします。
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.comgcloud 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 サービスをご覧ください。
エラー メッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。
詳しくは、Endpoints 構成をデプロイするをご覧ください。
新しい ESPv2 イメージをビルドする
新しい ESPv2 Docker イメージに Endpoints サービス構成をビルドします。その後、このイメージを予約済みの Cloud Run サービスにデプロイします。
新しい ESPv2 Docker イメージにサービス構成をビルドするには:
gcloud CLI がインストールされているローカルマシンにこのスクリプトをダウンロードします。
次のコマンドでスクリプトを実行します。
chmod +x gcloud_build_image./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_IDCLOUD_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-
このスクリプトは、
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 コンテナをデプロイする
前の手順で作成した新しいイメージを使用して、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
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 のフラグをご覧ください。- Cloud Run サービスを呼び出す権限を ESPv2 に付与します。各サービスに対して次のコマンドを実行します。次のコマンドを実行します。
- BACKEND_SERVICE_NAME は、呼び出す Cloud Run サービスの名前で置き換えます。`gcr.io/endpointsv2/python-grpc-bookstore-server:2`をデプロイして作成したサービスを使用している場合、
python-grpc-bookstore-serverをこの値として使用します。 - ESP_PROJECT_NUMBER は、ESPv2 に作成したプロジェクトのプロジェクト番号に置き換えます。この番号を調べる 1 つの方法としては、Google Cloud コンソールの [IAM] ページに移動して、デフォルトのコンピューティング サービス アカウントを探す方法があります。これは「member」フラグで使用されているサービス アカウントです。
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
- BACKEND_SERVICE_NAME は、呼び出す Cloud Run サービスの名前で置き換えます。`gcr.io/endpointsv2/python-grpc-bookstore-server:2`をデプロイして作成したサービスを使用している場合、
詳しくは、IAM を使用したアクセスの管理をご覧ください。
API にリクエストを送信する
サンプル API にリクエストを送信するには、Python で作成された gRPC クライアントを使用できます。
gRPC クライアント コードがホストされる git リポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
作業ディレクトリに移動します。
cd python-docs-samples/endpoints/bookstore-grpc/
依存関係をインストールします。
pip3 install virtualenv
virtualenv envsource env/bin/activatepip3 install -r requirements.txtサンプル API にリクエストを送信します。
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
CLOUD_RUN_HOSTNAME 内の ESPv2 Cloud Run サービスのホスト名をプロトコル識別子なしで指定します。例:
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
[エンドポイント] > [サービス] ページで API のアクティビティ グラフを確認します。
グラフにリクエストが反映されるまでしばらくかかります。
[ログ エクスプローラ] ページで、API のリクエストログを確認します。
正常なレスポンスが返されない場合は、レスポンス エラーのトラブルシューティングをご覧ください。
これで Endpoints の API のデプロイとテストが完了しました。
API の活動を追跡する
Google Cloud コンソールで [Endpoints] > [サービス] ページに移動して、API のアクティビティ グラフを表示します。
グラフにリクエストが反映されるまでしばらくかかります。
[ログ エクスプローラ] ページで、API のリクエストログを確認します。
API のデベロッパー ポータルを作成する
Cloud Endpoints Portal を使用してデベロッパー ポータルを作成できます。デベロッパー ポータルとは、サンプル API の操作に使用できるウェブサイトです。詳細については、Cloud Endpoints Portal の概要をご覧ください。
クリーンアップ
このページで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の手順を行います。
このチュートリアルで使用したサービスを停止する場合は、API と API インスタンスを削除するをご覧ください。