ESP を使用した Kubernetes 用 Endpoints のスタートガイド

OpenAPI | gRPC

このチュートリアルでは、Google Cloud で実行されない Kubernetes クラスタに、Extensible Server Proxy（ESP）を使用して単純なサンプル gRPC サービスをデプロイする方法について説明します。このチュートリアルでは、bookstore-grpc サンプルの Python 版を使用しています。他の言語の gRPC サンプルについては、次のステップセクションをご覧ください。

このチュートリアルでは、事前にビルドしたサンプルコードと ESP のコンテナイメージを使用します（これらは、Container Registry に保存されています）。コンテナをまだよく理解していない場合は、次の情報をご覧ください。

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

目標

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

Google Cloud プロジェクトをセットアップして、必要なソフトウェアをダウンロードします。始める前にをご覧ください。
bookstore-grpc サンプルからファイルをコピーして構成します。Cloud Endpoints の構成をご覧ください。
Endpoints 構成をデプロイして Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
Endpoints サービスの認証情報を作成します。サービスの認証情報を作成するをご覧ください。
API を提供するバックエンドを作成し、API をデプロイします。API バックエンドをデプロイするをご覧ください。
サービスの外部 IP アドレスを取得します。サービスの外部 IP アドレスを取得するをご覧ください。
API にリクエストを送信します。API にリクエストを送信するをご覧ください。
Google Cloud アカウントへの課金が発生しないようにします。クリーンアップをご覧ください。

料金

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

Endpoints

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

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

始める前に

このチュートリアルは、すでに Minikube または Kubernetes クラスタが設定済みであることを前提としています。詳細については、Kubernetes のドキュメントをご覧ください。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

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

Google Cloud プロジェクトで課金が有効になっていることを確認します。

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

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

Google Cloud プロジェクトで課金が有効になっていることを確認します。

後で必要になるので、Google Cloud プロジェクト ID はメモしておいてください。
gcloud CLI をインストールして初期化します。
gcloud CLI を更新し、Endpoints コンポーネントをインストールします。
```
gcloud components update
```
Google Cloud CLI（gcloud）が、Google Cloud にある対象のデータとサービスへのアクセスが許可されていることを確認します。
```
gcloud auth login
```
表示される新しいタブで、アカウントを選択します。
デフォルトプロジェクトを実際のプロジェクト ID に設定します。
```
gcloud config set project
    YOUR_PROJECT_ID
```
YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。

他にも Google Cloud プロジェクトがある場合、gcloud を使ってそれらのプロジェクトを管理するには、gcloud CLI 構成の管理をご覧ください。
kubectl のインストール:
```
gcloud components install kubectl
```
アプリケーションのデフォルト認証情報用に使用する新しいユーザー認証情報を取得します。ユーザー認証情報は kubectl を承認するために必要です。
```
gcloud auth application-default login
```
表示された新しいブラウザタブで、アカウントを選択します。
gRPC Python クイックスタートの手順に沿って、gRPC と gRPC ツールをインストールします。

Endpoints の設定

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

サービスの .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 を変更します。
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 コマンドを使用します。このコマンドは、Google の基礎的なサービスプラットフォームである Service Infrastructure を使用します。このプラットフォームは、Endpoints やその他のサービスで API やサービスを作成、管理するために使用されます。

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.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 を管理するには、ESP と ESPv2 のどちらにも Service Infrastructure のサービスが必要です。これらのサービスを呼び出すには、ESP と ESPv2 ではアクセストークンを使用する必要があります。GKE や Compute Engine などの Google Cloud 環境に ESP または ESPv2 をデプロイする場合、ESP と ESPv2 は Google Cloud メタデータサービスを通じてアクセストークンを取得します。

ローカルデスクトップ、オンプレミスの Kubernetes クラスタ、別のクラウドプロバイダなど、Google Cloud 以外の環境に ESP または ESPv2 をデプロイする場合は、秘密鍵を含むサービスアカウントの JSON ファイルを指定する必要があります。ESP と ESPv2 は、サービスアカウントを使用してアクセストークンを生成し、API の管理に必要なサービスを呼び出します。

Google Cloud コンソールまたは Google Cloud CLI を使用して、サービスアカウントと秘密鍵ファイルを作成できます。

Console

Google Cloud コンソールで [サービスアカウント] ページを開きます。
[サービスアカウント] ページに移動
[プロジェクトの選択] をクリックします。
API が作成されたプロジェクトを選択し、[開く] をクリックします。
[+ サービスアカウントを作成] をクリックします。
[サービスアカウント名] 項目に、サービスアカウントの名前を入力します。
[作成] をクリック
[続行] をクリックします。
[完了] をクリックします。
新しく作成したサービスアカウントのメールアドレスをクリックします。
[キー] をクリックします。
[鍵を追加]、[新しい鍵を作成] の順にクリックします。
[作成] をクリックします。JSON キーファイルがパソコンにダウンロードされます。

鍵ファイルは、サービスアカウントとしての認証で使用できるため、安全な場所に保管してください。このファイルは任意の場所に移動できます。名前の変更も可能です。
[閉じる] をクリックします。

`gcloud`

次のコマンドを入力して、Google Cloud プロジェクトのプロジェクト ID を表示します。
```
gcloud projects list
```
次のコマンドの PROJECT_ID の部分を API が含まれているプロジェクトに置き換えて、デフォルトのプロジェクトに設定します。
```
gcloud config set project PROJECT_ID
```
重要: API が含まれているプロジェクトと同じプロジェクト内でサービスアカウントを作成する必要があります。
Google Cloud CLI（gcloud）が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
```
gcloud auth login
```
アカウントが複数ある場合は、API がある Google Cloud プロジェクトのアカウントを選択してください。gcloud auth list を実行すると、選択したアカウントがプロジェクトの有効なアカウントとして表示されます。
サービスアカウントを作成するには、次のコマンドを実行します。このとき、SERVICE_ACCOUNT_NAME と My Service Account は、使用する名前と表示名に置き換えます。
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
このコマンドは、サービスアカウントのメールアドレスを次の形式で割り当てます。

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

このメールアドレスは、後で実行するコマンドで必要になります。

サービスアカウントのキーファイルを作成します。

gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

必要な IAM ロールを追加する

このセクションでは、ESP と ESPv2 で使用される IAM リソースと、これらのリソースにアクセスするために接続されたサービスアカウントに必要な IAM ロールについて説明します。

エンドポイントサービスの構成

ESP と ESPv2 は、エンドポイントサービス構成を使用する Service Control を呼び出します。エンドポイントサービスの構成は IAM リソースであり、ESP と ESPv2 にはサービスコントローラロールが必要です。

IAM ロールは、プロジェクトではなく、エンドポイントサービスの構成に対するものです。1 つのプロジェクトには、複数のエンドポイントサービス構成が存在する場合があります。

次の gcloud コマンドを使用して、エンドポイントサービス構成の接続されたサービスアカウントにロールを追加します。

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

ここで、
* SERVICE_NAME は、エンドポイントサービス名です。
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com は、接続されたサービスアカウントです。

Cloud Trace

ESP と ESPv2 は Cloud Trace サービスを呼び出して、Trace をプロジェクトにエクスポートします。このプロジェクトはトレースプロジェクトと呼ばれます。ESP では、トレースプロジェクトと、エンドポイントサービス構成を有するプロジェクトは同じです。ESPv2 では、トレースプロジェクトはフラグ --tracing_project_id で指定できます。デフォルトはデプロイプロジェクトです。

ESP と ESPv2 では、Cloud Trace を有効にするために、Cloud Trace エージェントロールが必要です。

次の gcloud コマンドを使用して、接続されたサービスアカウントにロールを追加します。

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

ここで、
* TRACING_PROJECT_ID は、トレースプロジェクト ID です。
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com は、接続されたサービスアカウントです。詳細については、ロールと権限についてをご覧ください。

コマンドの詳細については、gcloud iam service-accounts をご覧ください。

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

ここまでの手順でサービス構成を Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイされていません。ここでは、サンプル API と ESP 用のビルド済みコンテナを Kubernetes にデプロイする手順を説明します。

ESP にサービス認証情報を提供する

コンテナ内で実行される ESP は、service-account-creds.jsonファイルにローカルに保存されている認証情報にアクセスする必要があります。ESP から認証情報にアクセスできるようにするには、Kubernetes Secret を作成し、その Kubernetes Secret を Kubernetes ボリュームとしてマウントします。

Kubernetes シークレットを作成してボリュームをマウントするには:

Google Cloud コンソールを使用してサービスアカウントを作成した場合は、JSON ファイルの名前を service-account-creds.json に変更します。そのファイルを api_descriptor.pb と api_config.yaml ファイルが配置されているディレクトリに移動します。
サービスアカウントの認証情報を使用して Kubernetes シークレットを作成します。
```
 kubectl create secret generic service-account-creds
      --from-file=service-account-creds.json
```
成功すると、secret "service-account-creds" created というメッセージが表示されます。

API と ESP を Kubernetes にデプロイするために使用するデプロイメントマニフェストファイルには、Secret ボリュームがすでに含まれています。これは、ファイルの以下の 2 つのセクションに示されています。

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

サービス名を構成してサービスを開始する

ESP では、gcloud endpoints services deploy コマンドを使用して以前にデプロイされた構成を見つけるために、サービスの名前を知る必要があります。

サービス名を構成してサービスを開始するには:

デプロイメントマニフェストファイル k8s-grpc-bookstore.yaml のコピーを service-account-creds.json と同じディレクトリに保存します。
k8s-grpc-bookstore.yaml を開き、SERVICE_NAME を Endpoints サービスの名前に置き換えます。これは、api_config.yaml ファイルの name フィールドで構成した名前と同じです。
```
containers:
  - name: esp
    image: gcr.io/endpoints-release/endpoints-runtime:1
    args: [
      "--http2_port=9000",
      "--service=SERVICE_NAME",
      "--rollout_strategy=managed",
      "--backend=grpc://127.0.0.1:8000",
      "--service_account_key=/etc/nginx/creds/service-account-creds.json"
    ]
```
--rollout_strategy=managed オプションを指定すると、デプロイ済みの最新のサービス構成を使用するように ESP が構成されます。このオプションを指定すると、新しいサービス構成をデプロイしてから 5 分以内に ESP が変更を検出し、自動的に使用します。ESP が特定の構成 ID でなく、このオプションを使用するようにしてください。ESP 引数の詳細については、ESP 起動オプションをご覧ください。

注: MiniKube を使用している場合は、構成ファイル内でサービス type フィールドを LoadBalancer から NodePort に変更する必要があります。
注: 上記のコンテナ仕様の imagePullPolicy を Always に設定することをおすすめします。この設定により、新しく作成された Pod は常に ESP の最新バージョンを pull することが許可されます。詳細については、構成のベストプラクティスをご覧ください。ESP の新しいバージョンがリリースされたら、すべての Pod をローリング再起動して、最新バージョンを使用できるようにします。
サービスを開始して、Kubernetes にサービスをデプロイします。
```
kubectl create -f k8s-grpc-bookstore.yaml
```
次のようなエラーメッセージが表示される場合があります。
```
The connection to the server localhost:8080 was refused - did you specify the right host or port?
```
これは、kubectl が正しく構成されていないことを示しています。詳細については、kubectl を構成するをご覧ください。

サービスの外部 IP アドレスを取得する

サンプル API にリクエストを送信するには、サービスの外部 IP アドレスが必要です。コンテナでサービスを開始してから外部 IP アドレスを確認できるまで数分かかる場合があります。

外部 IP アドレスを表示します。
```
kubectl get service
```
EXTERNAL-IP の値をメモし、サンプル API へのリクエストの送信時に使われる SERVER_IP 環境変数にそれを保存します。
```
export SERVER_IP=YOUR_EXTERNAL_IP
```

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

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

gRPC クライアントコードがホストされる git リポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
   
```

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

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

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

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

サンプル API にリクエストを送信します。
```
python bookstore_client.py --host SERVER_IP --port 80
```
- [エンドポイント] > [サービス] ページで API のアクティビティグラフを確認します。
  
  [Endpoints] の [サービス] ページに移動
  
  グラフにリクエストが反映されるまでしばらくかかります。
- [ログエクスプローラ] ページで、API のリクエストログを確認します。
  
  [ログエクスプローラ] ページに移動

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

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

クリーンアップ

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

API を削除します。
```
gcloud endpoints services delete SERVICE_NAME
```
SERVICE_NAME は、API の名前に置き換えます。

GKE クラスタを削除します。

gcloud container clusters delete NAME --zone ZONE

次のステップ

Endpoints で独自の gRPC API を構成する方法を学習する。
DNS を構成する。
- cloud.goog ドメインで DNS を設定する。
- ドメイン名を確認
GitHub の Bookstore サンプルアプリで詳細を確認する。クライアントとサーバーのどちらも Python と Java で利用できます。
GitHub には、次の言語の getting-started-grpc のサンプルがあります。
- Java
- Python
- Ruby
- Go
- Node.js

ESP を使用した Kubernetes 用 Endpoints のスタートガイド

目標

料金

始める前に

Endpoints の設定

Endpoints 構成をデプロイする

必要なサービスの確認

サービスの認証情報を作成する

Console

gcloud

エンドポイント サービスの構成

Cloud Trace

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

ESP にサービス認証情報を提供する

サービス名を構成してサービスを開始する

サービスの外部 IP アドレスを取得する

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

クリーンアップ

次のステップ

`gcloud`

エンドポイントサービスの構成