ESPv2 を使用して Knative serving 用の Cloud Endpoints gRPC を設定する

Knative serving を有効にした GKE クラスタを作成する

クラスタを作成して、Google Cloud 上の Knative serving 用に有効にするには:

1. 次のコマンドで新しいクラスタを作成します。

   gcloud container clusters create CLUSTER_NAME \ 
     --addons=HttpLoadBalancing,CloudRun \ 
     --machine-type=n1-standard-4 \ 
     --num-nodes=3

   CLUSTER_NAME は、クラスタに付ける名前で置き換えます。

   これらの手順では、クラスタの自動スケーリングを有効にしてクラスタのサイズを変更することはできませんが、Google Cloud の Knative serving ではクラスタ内のインスタンスが自動的にスケーリングされます。

2. クラスタの作成が完了するまで待機します。作成プロセス中に、次のようなメッセージが表示されます。

   Creating cluster CLUSTER_NAME...done. 
   Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

   また、出力には、出力の NODE_VERSION 列のクラスタのバージョンも示されます。たとえば、1.15.11-gke.1 や 1.14.10-gke.27 です。このドキュメントの後半で使用するので、クラスタのバージョンをメモしておいてください。

3. gcloud CLI を使用するときに指定しなくても済むように、新しいクラスタとクラスタのロケーションを gcloud のデフォルトに設定します。

   gcloud config set run/cluster CLUSTER_NAME
   gcloud config set run/cluster_location ZONE

4. 次のコマンドを使用して、新しいクラスタの詳細を表示します。

   gcloud container clusters describe CLUSTER_NAME

5. 次のコマンドを使用して、クラスタの認証情報を取得します。

   gcloud container clusters get-credentials CLUSTER_NAME

サンプルの gRPC Cloud Run サービスをデプロイする

作成したクラスタに「grpc-bookstore」Cloud Run for Anthos のサンプルコンテナをデプロイするには:

1. gRPC Python クイックスタートの手順に沿って、gRPC と gRPC ツールをインストールします。

2. この gRPC サーバーのサンプルには、Python の「grpc-bookstore service」のビルド済み Docker イメージが含まれています: gcr.io/endpointsv2/python-grpc-bookstore-server:2。「grpc-bookstore」をクラスタにデプロイするには、次のコマンドを使用します。

   gcloud run deploy GRPC_SERVICE \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
    --connectivity=internal \
     --use-http2

   サービスが外部からアクセスできないように、これを内部サービスとして指定します。

   GRPC_SERVICE は、サービスに付ける名前で置き換えます。例:

   gcloud run deploy grpc-bookstore \
     --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2 \
     --platform=gke \
     --connectivity=internal \
     --use-http2

   完了すると、次のメッセージが表示されます。

   Service [grpc-bookstore] revision [grpc-bookstore-00001-nuk] has been deployed and is serving 100 percent of traffic at http://grpc-bookstore.default.svc.cluster.local

   内部サービスを作成すると、GKE によって DNS 名（この例では grpc-bookstore.default.svc.cluster.local）が作成されます。この DNS 名はクラスタ自体から発信されるリクエストの場合のみ解決でき、外部リクエストの場合は解決できません。外部のクラスタからこの DNS にアクセスすることはできません。詳細については、Cloud Run サービスをご覧ください。

3. サービスが正常に動作していることを確認するには、同じ Docker イメージを使用してポッドをクラスタにデプロイします。イメージには、内部サービスのテストに使用できる「grpc-bookstore」用の gRPC クライアント コードが含まれています。

   1. 上記と同じクラスタにポッドをデプロイするには、次の kubectl コマンドを使用します。

      kubectl run grpc --generator=run-pod/v1 \
        --image=gcr.io/endpointsv2/python-grpc-bookstore-server:2

      このイメージには、クラスタ内からクライアント リクエストを行うために使用できる bookstore_client.py スクリプトが含まれています。

      注: kubectl の新しいバージョンでは、このコマンドによって次の警告が表示されることがあります。

      Flag --generator has been deprecated, has no effect and will be removed in the future".

      この警告は無視しても問題ありません。

   2. 前の手順で Docker イメージをデプロイしたときに、クラスタに作成された「grpc-bookstore」Pod の名前を取得します。

      kubectl get pods

      出力は次の形式のようになります。

      NAME   READY    STATUS    RESTARTS   AGE
      grpc   1/1      Running   0          23h

      ここで、grp は「grpc-bookstore」Pod の名前です。続行する前に、Pod の [ステータス] が [実行中] であることを確認します。

   3. 次のコマンドを使用して、「grpc-bookstore」サービスに対してクライアント リクエストを行います。

      kubectl exec grpc -ti -- python3 bookstore_client.py \
        --host grpc-bookstore.default.svc.cluster.local --port=80

      このコマンドは、クラスタ内で bookstore_client.py スクリプトを内部的に実行し、gRPC リクエストをホスト名 grpc-bookstore.default.svc.cluster.local の「grpc-bookstore」サービスに送信します。

      すべてが正常に機能している場合、次のような形式のレスポンスが返されます。

      ListShelves: shelves {
        id: 1
        theme: "Fiction"
      }
      shelves {
        id: 2
        theme: "Fantasy"
      }

Endpoints を構成する

バックエンド サービスのサーフェスと認証要件を記述する gRPC API 仕様が必要です。

gRPC API 仕様の name フィールドの設定について

gRPC API 仕様の name フィールドで、Cloud Run for Anthos サービスへのアクセスに使用する Endpoints サービス名を指定します。Endpoints サービス名は、ドメイン名の形式になっています。

API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

Endpoints サービス名はドメイン名に対応しているため、名前は次のルールに従う必要があります。

• 使用できるのは小文字、数字、ピリオド、ダッシュのみです。
• ダッシュで始めることはできません。
• アンダースコアを含めることはできません。

例:

grpc-boostore-api.endpoints.ESP_PROJECT_ID.cloud.goog

gRPC API 仕様の作成

bookstore-grpc サンプルには、ローカルにコピーして構成する必要のあるファイルが含まれています。

1. gRPC API 仕様用の新しいディレクトリ（my-anthos-grpc など）を作成します。次に、cd を実行してこのディレクトリに移動します。

2. gRPC クライアント コードが新しいディレクトリに対してホストされる git リポジトリのクローンを作成します。

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

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

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

   このディレクトリには bookstore.proto ファイルが含まれます。このファイルによって、Bookstore サービスの API が定義されます。

4. サービスの .proto ファイルから、自己完結型 protobuf 記述子ファイルを作成します。

   1. 作業ディレクトリの下に generated_pb2 ディレクトリを作成します。

   2. 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 を変更します。

5. 現在の作業ディレクトリ（bookstore.proto を含む同じディレクトリ）の api_config_anthos.yaml ファイルを変更して、ファイルに次の内容を追加します。

   type: google.api.Service
   config_version: 3
   #
   # Name of the service configuration.
   #
   name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
   #
   # API title to appear in the user interface (Google Cloud console).
   #
   title: Bookstore gRPC API In Cloud Run Anthors
   apis:
   - name: endpoints.examples.bookstore.Bookstore
   #
   # Create a DNS record to map your service name to IP address
   #
   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS
   #
   # Specify the backend address to route to
   #
   backend:
     rules:
       - selector: "*"
         address: grpc://GRPC_SERVICE.default.svc.cluster.local
         disable_auth: true
   #
   # API usage restrictions.
   #
   usage:
     rules:
     # ListShelves methods can be called without an API Key.
     - selector: endpoints.examples.bookstore.Bookstore.ListShelves
       allow_unregistered_calls: true

   yaml 形式ではインデントが重要です。

6. name フィールドに、Cloud Run for Anthos サービスへのアクセスに使用する Endpoints API のドメイン名を次の形式で指定します。

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

   例:

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. endpoints セクションでは、cloud.goog ドメインにあるエンドポイント サービスの DNS エントリを次の形式で登録します。

   endpoints:
     - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
       target: IP_ADDRESS

   IP_ADDRESS は、クラスタの istio-ingress サービスの IP です。この IP アドレスを確認する方法は次のとおりです。

   1. Cloud コンソールで Google Kubernetes Engine ページに移動します。

      Google Kubernetes Engine に移動

   2. 左側のナビゲーション パネルで、[Services と Ingress] をクリックして、サービスのリストを表示します。

   3. クラスタ バージョンが 1.15.3-gke.19 以降、1.14.3-gke.12 以降、1.13.10-gke.8 以降のいずれかに相当する場合は、下方向にスクロールして istio-ingress サービスを表示します。それ以外のクラスタ バージョンの場合は、istio-ingressgateway サービスまで下にスクロールします。

   4. ロードバランサの横に表示されている外部 IP アドレスをコピーします。このとき、ポート設定（表示されている場合）は省きます。たとえば、IP が XX.XXX.XX.XXX:15020 の場合、:15020 は省略します。表示されている他の IP アドレスは無視してください。

8. backend セクションの address フィールドは、Cloud Run の「grpc-bookstore」サービスの内部 DNS 名をプロトスキーム grpc:// で指定し、このサービスへの認証を無効にします。

   address: grpc://GRPC_SERVICE.default.svc.cluster.local
   disable_auth: true

   例:

   address: grpc://grpc-bookstore.default.svc.cluster.local
   disable_auth: true

   これは、ESPv2 から Cloud Run for Anthos サービスへの呼び出しがクラスタ内から内部呼び出しとして行われるために必要です。したがって、認証は必要ありません。

9. api_config_authos.yaml ファイルの title プロパティの値をメモします。

   title: Bookstore gRPC API In Cloud Run Anthos

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

10. gRPC API のドキュメントを保存します。

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

Endpoints 構成をデプロイする

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

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

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

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

   gcloud endpoints services deploy api_descriptor.pb api_config_anthos.yaml \ 
     --project ESP_PROJECT_ID

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

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

   Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]

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

   Service Configuration [2019-02-01r0] uploaded for service [grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog] 

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

   エラー メッセージが表示された場合は、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 Knative serving イメージをビルドする

新しい ESPv2 Docker イメージに Endpoints サービス構成をビルドします。このイメージを作成したら、それをクラスタにデプロイできます。

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

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

   chmod +x gcloud_build_image 
   ./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ 
   -c CONFIG_ID -p ESP_PROJECT_ID

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

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID

ESPv2 Knative serving イメージをデプロイする

ESPv2 Knative serving サービスのイメージをクラスタにデプロイします。

1. 新しいイメージで ESPv2 Knative serving サービスをデプロイします。

   gcloud run deploy ESP_V2_SERVICE_NAME \ 
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --platform gke \
     --use-http2 \
     --project=ESP_PROJECT_ID

   ESP_PROJECT_ID には、ESPv2 サービスに使用する名前を指定します。この例では、ESP_V2_SERVICE_NAME を espv2 に設定します。

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

   gcloud run deploy ESP_V2_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
     --platform gke --use-http2 \
     --project ESP_PROJECT_ID

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

ESPv2 Knative serving サービスにドメイン マッピングを作成する

リクエスト時に host ヘッダーを省略できるようにするには、ESPv2 サービスのドメイン マッピングを追加します。

1. Cloud Run に移動

2. [カスタムドメインの管理] を選択します。

3. [マッピングを追加] を選択します。

4. プルダウンから、[サービス ドメイン マッピングを追加] を選択します。

5. [マッピングを追加] のポップアップの [マッピング先のサービスを選択] フィールドで、ESPv2 サービスを選択します。

6. [ドメイン名を入力] フィールドに、Endpoints を介して Knative serving サービスにアクセスするために使用するドメイン名を指定します。例:

   API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

   ここで、API_NAME は Endpoints API の名前です。この例では、「hello-api」を使用できます。

   grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog

7. [続行] をクリックします。マッピングの概要が表示されます。

8. [完了] を選択してマッピングを保存します。

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

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

1. gRPC ドキュメント（api_config_anthos.yaml など）を含むディレクトリにいることを確認します。

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

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

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

   python3 bookstore_client.py --host API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

   例:

   python3 bookstore_client.py --host grpc-bookstore-api.endpoints.ESP_PROJECT_ID.cloud.goog --port 80

   すべてが正常に機能している場合、次のような形式のレスポンスが返されます。

   ListShelves: shelves {
     id: 1
     theme: "Fiction"
   }
   shelves {
     id: 2
     theme: "Fantasy"
   }

   • [エンドポイント] > [サービス] ページで API のアクティビティ グラフを確認します。

     [Endpoints] の [サービス] ページに移動

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

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

     [ログ エクスプローラ] ページに移動

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

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

HTTPS を使用するように Endpoints API を構成する

Google Cloud 上の Knative serving では、自動 TLS サポートはデフォルトで無効になっています。そのため、この例では ESPv2 を介して Endpoints API にアクセスする際に、HTTP を使用して呼び出しを行います。

HTTPS を使用してリクエストをサポートするように ESPv2 を構成できます。内部バックエンド サービスである「hello」ではなく、外部サービスである ESPv2 で HTTPS サポートを構成します。

ESPv2 で HTTPS をサポートするには、次の手順を行う必要があります。

1. ドメインを所有している。ドメインをお持ちでない場合は、Google または別のドメイン ベンダーからドメインを取得します。

2. ESPv2 サービスのドメイン マッピングを作成し、ドメイン マッピング ページの手順に沿って DNS レコードを更新する。

   Google Domains からドメインを取得した場合は、そのドメインを DNS サーバーとして使用します。それ以外の場合は、Cloud DNS または任意の DNS サーバーを使用します。Google Domains のドメインを使用するのが最も簡単な方法です。

3. Endpoints OpenAPI 仕様:

   1. name フィールドを *.cloud.goog ではなくドメインを参照するように設定します。

   2. endpoints タグとその 2 つの子プロパティを削除します。

詳細な手順とチュートリアルについては、HTTPS 証明書と自動 TLS 証明書を有効にするをご覧ください。

API の活動を追跡する

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

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

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

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

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

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

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