ESPv2 を使用したマネージド インスタンス グループ用の Cloud Endpoints gRPC のスタートガイド

このチュートリアルでは、マネージド インスタンス グループExtensible Service Proxy V2(ESPv2)を使用して簡単なサンプル gRPC サービスをデプロイする方法について説明します。

このチュートリアルでは、bookstore-grpc サンプルの Python 版を使用しています。他の言語の gRPC サンプルについては、次のステップ セクションをご覧ください。

Cloud Endpoints の概要については、Endpoints についてEndpoints アーキテクチャをご覧ください。

目標

タスクの概要を示す次のリストを参照しながら、チュートリアルを実施してください。API にリクエストを送信するには、すべてのタスクを行う必要があります。

  1. Google Cloud プロジェクトをセットアップして、必要なソフトウェアをダウンロードします。始める前にをご覧ください。
  2. bookstore-grpc サンプルからファイルをコピーして構成します。Endpoints を構成するをご覧ください。
  3. Endpoints 構成をデプロイして Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
  4. マネージド インスタンス グループのバックエンドに API と ESPv2 をデプロイします。API バックエンドをデプロイするをご覧ください。
  5. API にリクエストを送信します。API にリクエストを送信するをご覧ください。
  6. Google Cloud アカウントへの課金が発生しないようにします。クリーンアップをご覧ください。

料金

このチュートリアルでは、課金対象である次の Google Cloud コンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

  1. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
  2. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  3. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  4. Google Cloud Console の [プロジェクト セレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

    プロジェクト セレクタに移動

  5. Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する

  6. 後で必要になるため、プロジェクト ID をメモしておきます。
  7. Cloud SDK をインストールし、初期化します
  8. Cloud SDK を更新し、Endpoints コンポーネントをインストールします。
    gcloud components update
  9. Cloud SDK(gcloud)が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
    gcloud auth login
    表示された新しいブラウザタブで、アカウントを選択します。
  10. プロジェクト ID にデフォルト プロジェクトを設定します。
    gcloud config set project YOUR_PROJECT_ID

    YOUR_PROJECT_ID を実際のプロジェクト ID に置き換えます。他にも Google Cloud プロジェクトがあり、gcloud を使用してそのプロジェクトを管理する場合は、Cloud SDK 構成の管理をご覧ください。

  11. gRPC Python クイックスタートの手順に従い、gRPC と gRPC ツールをインストールします。

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

Endpoints の設定

GitHub から bookstore-grpc サンプルリポジトリのクローンを作成します。

Endpoints を設定するには:

  1. サービスの .proto ファイルから、自己完結型 protobuf 記述子ファイルを作成します。
    1. サンプル リポジトリから、bookstore.proto のコピーを保存します。このファイルは Bookstore サービスの API を定義します。
    2. 次のコマンドでディレクトリを作成します。mkdir generated_pb2
    3. protoc プロトコル バッファ コンパイラを使用して、記述子ファイル api_descriptor.pb を作成します。bookstore.proto を保存したディレクトリで次のコマンドを実行します。
      python -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 を変更します。

  2. gRPC API 構成 YAML ファイルを作成します。
    1. api_config.yaml ファイルのコピーを保存します。このファイルは、Bookstore サービスの gRPC API 構成を定義します。
    2. api_config.yaml ファイルの MY_PROJECT_ID は、実際の Google Cloud プロジェクト ID で置き換えます。例:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      このファイルの apis.name フィールド値は、.proto ファイルの完全修飾 API 名と完全に一致させる必要があります。一致しなければ、デプロイは機能しません。Bookstore サービスは、パッケージ endpoints.examples.bookstore 内の bookstore.proto で定義されています。この完全修飾 API 名は、api_config.yaml ファイルと同じように endpoints.examples.bookstore.Bookstore になります。

      apis:
        - name: endpoints.examples.bookstore.Bookstore
      

詳細については、Endpoints を構成するをご覧ください。

Endpoints 構成をデプロイする

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

  1. api_descriptor.pb ファイルと api_config.yaml ファイルがあるディレクトリにいることを確認します。
  2. gcloud コマンドライン ツールが現在使用しているデフォルト プロジェクトが、エンドポイント構成をデプロイする Google Cloud プロジェクトであることを確認します。それには、次のコマンドを使用して返されるプロジェクト ID を確認してください。これは、間違ったプロジェクト内にサービスが作成されないようにするためです。
    gcloud config list project
    

    デフォルト プロジェクトを変更する必要がある場合は、次のコマンドを実行します。

    gcloud config set project YOUR_PROJECT_ID
    
  3. 次の gcloud コマンドライン ツールを使用して、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.com
gcloud services enable servicecontrol.googleapis.com
gcloud 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 構成をデプロイするをご覧ください。

API バックエンドをデプロイする

ここまでの手順で API 構成を Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。このセクションでは、マネージド インスタンス グループで Docker を設定し、Docker コンテナで API バックエンド コードと ESPv2 を実行する方法について説明します。

インスタンス テンプレートの作成

VM インスタンスのグループの作成に使用するテンプレートを作成します。テンプレートから作成された各インスタンスが、ESPv2 とバックエンド アプリケーション サーバーを起動します。

  1. Google Cloud Console で、[インスタンス テンプレート] ページに移動します。

    [インスタンス テンプレート] に移動

  2. [インスタンス テンプレートを作成] をクリックします。

  3. [名前] に「load-balancing-espv2-template」と入力します。

  4. [マシンの構成] で、[マシンタイプ] を e2-micro に設定します。

  5. [ブートディスク] で、[イメージ] を Container Optimized OS stable version に設定します。

  6. [ファイアウォール] で、[HTTP トラフィックを許可する] をオンにします。

  7. [管理、セキュリティ、ディスク、ネットワーク、単一テナンシー] をクリックして、詳細設定を表示します。

  8. [管理] タブをクリックします。[自動化] に、次の起動スクリプトを入力します。 ENDPOINTS_SERVICE_NAME を必ず更新してください。

    sudo docker network create --driver bridge esp_net
    sudo docker run \
      --detach \
      --name=bookstore \
      --net=esp_net \
      gcr.io/endpointsv2/python-grpc-bookstore-server:1
    sudo docker run \
      --detach \
      --name=esp \
      --publish=80:9000 \
      --net=esp_net \
      gcr.io/endpoints-release/endpoints-runtime:2 \
      --service=ENDPOINTS_SERVICE_NAME \
      --rollout_strategy=managed \
      --listener_port=9000 \
      --healthz=/healthz \
      --backend=grpc://bookstore:8000
    

    このスクリプトは、インスタンスの起動時に echo アプリケーション サーバーと ESPv2 プロキシ サーバーを取得してインストールし、起動します。

  9. [作成] をクリックします。

続行する前に、テンプレートの作成が完了するまでお待ちください。

リージョン マネージド インスタンス グループを作成する

アプリケーションを実行するには、インスタンス テンプレートを使用してリージョン マネージド インスタンス グループを作成します。

  1. Google Cloud Console で、[インスタンス グループ] ページに移動します。

    [インスタンス グループ] に移動

  2. [インスタンス グループを作成] をクリックします。

  3. [名前] に「load-balancing-espv2-group」と入力します。

  4. [ロケーション] で、[複数のゾーン] を選択します。

  5. [リージョン] で、us-central1 を選択します。

  6. [ゾーンを構成] プルダウン メニューをクリックして、[ゾーン] を表示します。次のゾーンを選択します。

    • us-central1-b
    • us-central1-c
    • us-central1-f
  7. [インスタンス テンプレート] で load-balancing-espv2-template を選択します。

  8. [自動スケーリング] で [自動スケーリングしない] を選択します。

  9. [インスタンス数] を「3」に設定します。

  10. [インスタンスの再配布] で、[オン] を選択します。

  11. [自動修復] と [ヘルスチェック] で、[ヘルスチェックをしない ] を選択します。

  12. [作成] をクリックします。そうすると、[インスタンス グループ] ページに戻ります。

ロードバランサを作成

このセクションでは、TCP トラフィックをインスタンス グループに振り分けるリージョン ロードバランサを作成するために必要な手順について説明します。

  1. Google Cloud Console で、[ロードバランサの作成] ページに移動します。

    [ロードバランサの作成] に移動

  2. [TCP 負荷分散] で [構成を開始] をクリックします。

  3. [インターネット接続または内部専用] で [インターネットから自分の VM へ] を選択します。

  4. [マルチリージョンまたはシングル リージョン] で [シングル リージョンのみ] を選択します。

  5. [バックエンド タイプ] で [バックエンド サービス] を選択します。

  6. [続行] をクリックします。

  7. [名前] に「espv2-load-balancer」と入力します。

  8. [バックエンドの構成] で、リージョン us-central1 を選択します。

  9. インスタンス グループ load-balancing-espv2-group を選択します。

  10. [ヘルスチェック] で、新しいヘルスチェックを作成します。

    • [名前] に「espv2-load-balancer-check」と入力します。
    • [プロトコル] が TCP、[ポート] が 80 であることを確認します。
  11. [フロントエンドの構成] で、ポート番号「80」を入力します。

  12. [確認と完了] で、以下を確認します。

    • [インスタンス グループ] が load-balancing-espv2-group
    • [リージョン] が us-central1
    • [プロトコル] が TCP
    • [IP:ポート] が EPHEMERAL:80
  13. ロードバランサが作成されたら、[ロードバランサ] ページで IP アドレスを見つけます。

    [ロードバランサ] に移動

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

Docker コンテナを実行しているインスタンスと同じインスタンスからリクエストを送信する場合は、SERVER_IPlocalhost に置き換えます。それ以外の場合は、SERVER_IP をインスタンスの外部 IP で置き換えます。

外部 IP アドレスを確認するには、次のコマンドを実行します。

gcloud compute instances list

サンプル API にリクエストを送信するには、Python で作成された gRPC クライアントを使用できます。

  1. gRPC クライアント コードがホストされる git リポジトリのクローンを作成します。

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
       

  2. 作業ディレクトリに移動します。

    cd python-docs-samples/endpoints/bookstore-grpc/
      

  3. 依存関係をインストールします。

    pip install virtualenv
    virtualenv env
    source env/bin/activate
    python -m pip install -r requirements.txt
    

  4. サンプル API にリクエストを送信します。

    python bookstore_client.py --host SERVER_IP --port 80
    

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

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

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

  1. Cloud SDK(gcloud)に Google Cloud のデータやサービスへのアクセスを許可します。

    gcloud auth login
    
  2. 次のコマンドを入力して、Google Cloud プロジェクトのプロジェクト ID を表示します。

    gcloud projects list
    
  3. 前の手順で表示されたプロジェクト ID から該当するプロジェクト ID を使用して、アプリケーションが存在するプロジェクトにデフォルトの Cloud プロジェクトを設定します。

    gcloud config set project [YOUR_PROJECT_ID]
    
  4. Cloud プロジェクト内のすべてのマネージド サービスの名前を取得します。

    gcloud endpoints services list
    
  5. Service Management からサービスを削除します。SERVICE_NAME は、削除するサービスの名前に置き換えます。

    gcloud endpoints services delete SERVICE_NAME
    

    gcloud endpoints services delete コマンドを実行しても、マネージド サービスはすぐに削除されません。マネージド サービスは 30 日間無効になり、その間に必要に応じてサービスを復元できます。30 日後、マネージド サービスは完全に削除されます。

  6. [ロードバランサ] ページに移動します。

    [ロードバランサ] に移動

    ヘルスチェック espv2-load-balancer-check とともに、ロードバランサ espv2-load-balancer を削除します。

  7. [インスタンス グループ] ページに移動

    [インスタンス グループ] に移動

    load-balancing-espv2-group の削除

  8. [インスタンス テンプレート] ページに移動します。

    [インスタンス テンプレート] に移動

    load-balancing-espv2-template を削除

次のステップ