ESPv2 を使用した Compute Engine 用の Endpoints のスタートガイド

このチュートリアルでは、Compute EngineDocker コンテナに組み込まれた Extensible Service Proxy V2(ESPv2)を使用して、gRPC サービスの簡単なサンプルをデプロイする方法を説明します。

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

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

目標

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

  1. Google Cloud プロジェクトをセットアップして、必要なソフトウェアをダウンロードします。始める前にをご覧ください。
  2. Compute Engine VM インスタンスを作成します。Compute Engine のインスタンスを作成するをご覧ください。
  3. bookstore-grpc サンプルからファイルをコピーして構成します。Endpoints を構成するをご覧ください。
  4. Endpoints 構成をデプロイして Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
  5. API と ESPv2 を Compute Engine VM でデプロイします。API バックエンドをデプロイするをご覧ください。
  6. API にリクエストを送信します。API にリクエストを送信するをご覧ください。
  7. 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. Google Cloud CLI をインストールして初期化します
  8. gcloud CLI を更新し、Endpoints コンポーネントをインストールします。
    gcloud components update
  9. Google Cloud CLI(gcloud)が、Google Cloud にある対象のデータとサービスへのアクセスが許可されていることを確認します。
    gcloud auth login
    表示された新しいブラウザタブで、アカウントを選択します。
  10. プロジェクト ID にデフォルト プロジェクトを設定します。
    gcloud config set project YOUR_PROJECT_ID

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

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

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

Compute Engine インスタンスの作成

Compute Engine のインスタンスを作成するには:

  1. Cloud Console で、[インスタンスの作成] ページに移動します。

    [インスタンスの作成] に移動

  2. [ファイアウォール] で [HTTP トラフィックを許可する] と [HTTPS トラフィックを許可する] を選択します。
  3. VM を作成するには、[作成] をクリックします。
  4. 必要なオプションを設定した状態の VM インスタンス作成ウィンドウのスクリーンショット

    インスタンスが起動するまで、しばらくお待ちください。準備が完了すると、[VM インスタンス] ページに緑色のステータス アイコン付きで表示されます。

  5. VM インスタンスに接続できることを確認します。
    1. 仮想マシン インスタンスのリストで、接続するインスタンスの行にある [SSH] をクリックします。
    2. これで、ターミナルを使用して Debian インスタンスで Linux コマンドを実行できるようになりました。
    3. インスタンスとの接続を切断するには、「exit」と入力します。
  6. 後で必要になるため、インスタンス名、ゾーン、外部 IP アドレスをメモします。

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. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
  2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.
    gcloud config list project
    

    If you need to change the default project, run the following command:

    gcloud config set project YOUR_PROJECT_ID
    
  3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

    Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

    Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
    

    In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration 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 バックエンドを処理するコードはまだデプロイしていません。このセクションでは、VM インスタンスで Docker を設定し、Docker コンテナで API バックエンド コードと ESPv2 を実行する方法について説明します。

VM インスタンスに Docker をインストールする

Docker を VM インスタンスにインストールするには:

  1. 次のコマンドを実行して、プロジェクトのゾーンを設定します。
    gcloud config set compute/zone YOUR_INSTANCE_ZONE
    

    YOUR_INSTANCE_ZONE は、インスタンスが実行されているゾーンに置き換えます。

  2. 次のコマンドを使用して、インスタンスに接続します。
    gcloud compute ssh INSTANCE_NAME
    

    INSTANCE_NAME は、VM インスタンス名に置き換えます。

  3. Docker のドキュメントを参照して Docker リポジトリを設定します。VM インスタンスの該当するバージョンとアーキテクチャ用の手順に従ってください。
    • Jessie 以降
    • x86_64 / amd64

Docker コンテナでサンプル API と ESPv2 を実行する

Docker コンテナで gRPC サンプル サービスと ESPv2 を実行して、クライアントで使用できるようにするには、次の手順に沿って操作します。

  1. VM インスタンスで、esp_net という独自のコンテナ ネットワークを作成します。
    sudo docker network create --driver bridge esp_net
    
  2. サンプル API を提供するサンプル Bookstore サーバーを実行します。
    sudo docker run \
        --detach \
        --name=bookstore \
        --net=esp_net \
        gcr.io/endpointsv2/python-grpc-bookstore-server:1
    
  3. あらかじめパッケージ化された ESPv2 Docker コンテナを実行します。ESPv2 起動オプションで、SERVICE_NAME を実際のサービス名に置き換えます。これは、api_config.yaml ファイルの name フィールドに構成した名前と同じです。例: bookstore.endpoints.example-project-12345.cloud.goog
    sudo docker run \
        --detach \
        --name=esp \
        --publish=80:9000 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:2 \
        --service=SERVICE_NAME \
        --rollout_strategy=managed \
        --listener_port=9000 \
        --backend=grpc://bookstore:8000
    

    --rollout_strategy=managed オプションを指定すると、デプロイ済みの最新のサービス構成を使用するように ESPv2 が構成されます。このオプションを指定すると、新しいサービス構成をデプロイしてから 1 分以内に ESPv2 が変更を検出し、自動的に使用します。ESPv2 が特定の構成 ID でなく、このオプションを使用するようにしてください。ESPv2 引数の詳細については、ESPv2 スタートアップ オプションをご覧ください。

エラー メッセージが表示された場合は、Compute Engine の Endpoints をトラブルシューティングするをご覧ください。

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

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

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

gcloud compute instances list

To send requests to the sample API, you can use a sample gRPC client written in Python.

  1. Clone the git repo where the gRPC client code is hosted:

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

  2. Change your working directory:

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

  3. Install dependencies:

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

  4. Send a request to the sample API:

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

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

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

クリーンアップ

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

  1. API を削除します。
    gcloud endpoints services delete SERVICE_NAME
    

    SERVICE_NAME は、実際のサービス名に置き換えます。

  2. Cloud Console で [VM インスタンス] ページに移動します。

    [VM インスタンス] に移動

  3. 削除するインスタンスのチェックボックスを選択します。
  4. インスタンスを削除するには、 [その他の操作] をクリックし、[削除] をクリックしてから、指示に沿って操作します。

次のステップ