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

OpenAPI | gRPC

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

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

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

目標

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

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

費用

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

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

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

始める前に

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.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

後で必要になるので、Google Cloud プロジェクト ID はメモしておいてください。
Google Cloud 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 を実際のプロジェクト ID に置き換えます。

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

Endpoints を構成する

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

Create a self-contained protobuf descriptor file from your service .proto file:
1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
2. Create the following directory: mkdir generated_pb2
3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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
```
  In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.
Create a gRPC API configuration YAML file:
1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:
```
#
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog
```
  Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.
```
apis:
  - name: endpoints.examples.bookstore.Bookstore
```

詳細については、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.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 コンソールの [Endpoints] ページに移動します。[サービス名] 列に、考えられる ENDPOINTS_SERVICE_NAME のリストが表示されます。
OpenAPI の場合、ENDPOINTS_SERVICE_NAME は OpenAPI 仕様の host フィールドで指定したものです。gRPC の場合、ENDPOINTS_SERVICE_NAME は gRPC Endpoints 構成の name フィールドで指定したものです。

gcloud コマンドの詳細については、gcloud サービスをご覧ください。

エラーメッセージが表示された場合は、Endpoints 構成のデプロイのトラブルシューティングをご覧ください。

詳しくは、Endpoints 構成をデプロイするをご覧ください。

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

ここまでの手順でサービス構成を Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。ここでは、API バックエンドをホストする GKE クラスタを作成して API をデプロイする手順を説明します。

コンテナクラスタの作成

コンテナネイティブのロードバランシングを使用するためには、クラスタに IP エイリアスが必要です。この例では、IP エイリアスを持つコンテナクラスタを作成します。

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

上記のコマンドにより、ゾーン us-central1-a で自動プロビジョニングされるサブネットワークを持つクラスタ espv2-demo-cluster が作成されます。

コンテナクラスタに対する `kubectl` の認証

kubectl を使用してクラスタリソースを作成し、管理するには、クラスタの認証情報を取得して kubectl で使用可能にする必要があります。この操作を行うには、次のコマンドを実行します。NAME は新しいクラスタ名、ZONE はクラスタゾーンで置き換えます。

gcloud container clusters get-credentials NAME --zone ZONE

必要な権限を確認する

ESP と ESPv2 は、IAM を使用して、呼び出し元の ID が、使用されている IAM リソースにアクセスするための十分な権限を持っているかどうかを確認する Google サービスを呼び出します。呼び出し元の ID は、ESP と ESPv2 をデプロイする、接続されたサービスアカウントです。

接続されたサービスアカウントは、GKE Pod にデプロイされると、ノードのサービスアカウントです。通常、それは、Compute Engine のデフォルトサービスアカウントです。この権限の推奨事項に従って、適切なノードのサービスアカウントを選択してください。

Workload Identity を使用する場合、ノードのサービスアカウントとは別のサービスアカウントを使用して Google サービスと通信できます。Pod 用の Kubernetes サービスアカウントを作成して ESP と ESPv2 を実行し、Google サービスアカウントを作成して Kubernetes サービスアカウントを Google サービスアカウントに関連付けることができます。

この手順に沿って、Kubernetes サービスアカウントを Google サービスアカウントに関連付けます。この Google サービスアカウントは、接続されているサービスアカウントです。

接続されたサービスアカウントがプロジェクトの Compute Engine のデフォルトサービスアカウントで、エンドポイントサービス構成が同じプロジェクトにデプロイされている場合、サービスアカウントには、IAM リソースにアクセスするための十分な権限があるため、続く IAM ロールの設定手順はスキップできます。これに該当しない場合は、次の IAM ロールを、接続されたサービスアカウントに追加する必要があります。

必要な 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は、接続されたサービスアカウントです。詳細については、ロールと権限についてをご覧ください。

SSL 鍵と証明書を構成する

コンテナネイティブのロードバランシングでは、TLS で暗号化する必要がある HTTP2 LB を使用します。そのため、GKE Ingress と ESPv2 に TLS 証明書をデプロイする必要があります。独自の証明書を使用することも、自己署名証明書を使用することもできます。

openssl を使用して自己署名証明書と鍵を作成します。「共通名（CN）」の入力を求められたら、必ず同じ FQDN bookstore.endpoints.MY_PROJECT_ID.cloud.goog を入力してください。この名前は、クライアントがサーバー証明書を確認するために使用します。
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout ./server.key -out ./server.crt
```
SSL 鍵と証明書を使用して Kubernetes secret を作成します。Secret は GKE Ingress と ESPv2 の両方に渡されるため、証明書は server.crt と tls.crt の 2 か所にコピーされることに注意してください。GKE Ingress は証明書パス tls.crt を探し、ESPv2 が証明書パス server.crt を探します。
```
kubectl create secret generic esp-ssl \
--from-file=server.crt=./server.crt --from-file=server.key=./server.key \
--from-file=tls.crt=./server.crt --from-file=tls.key=./server.key
```

サンプル API と ESPv2 のクラスタへのデプロイ

gRPC サンプルサービスをクラスタにデプロイし、クライアントで使用可能にするには:

このリポジトリを git clone して開き、grpc-bookstore.yaml デプロイマニフェストファイルを編集します。

SERVICE_NAME は、Ingress コンテナと ESPv2 コンテナの Endpoints サービスの名前に置き換えます。これは、api_config.yaml ファイルの name フィールドで構成した名前と同じです。

# Copyright 2016 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

# Use this file to deploy the container for the grpc-bookstore sample
# and the container for the Extensible Service Proxy (ESP) to
# Google Kubernetes Engine (GKE).

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: esp-grpc-bookstore
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.allow-http: "false"
spec:
  tls:
  - hosts:
    - SERVICE_NAME
    secretName: esp-ssl
  backend:
    serviceName: esp-grpc-bookstore
    servicePort: 443
---
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: esp-grpc-bookstore
spec:
  healthCheck:
    type: HTTP2
    requestPath: /healthz
    port: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: esp-grpc-bookstore
  annotations:
    service.alpha.kubernetes.io/app-protocols: '{"esp-grpc-bookstore":"HTTP2"}'
    cloud.google.com/neg: '{"ingress": true, "exposed_ports": {"443":{}}}'
    cloud.google.com/backend-config: '{"default": "esp-grpc-bookstore"}'
spec:
  ports:
  # Port that accepts gRPC and JSON/HTTP2 requests over TLS.
  - port: 443
    targetPort: 9000
    protocol: TCP
    name: esp-grpc-bookstore
  selector:
    app: esp-grpc-bookstore
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: esp-grpc-bookstore
spec:
  replicas: 1
  selector:
    matchLabels:
      app: esp-grpc-bookstore
  template:
    metadata:
      labels:
        app: esp-grpc-bookstore
    spec:
      volumes:
      - name: esp-ssl
        secret:
          secretName: esp-ssl
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=SERVICE_NAME",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000",
          "--healthz=/healthz",
          "--ssl_server_cert_path=/etc/esp/ssl",
        ]
        ports:
          - containerPort: 9000
        volumeMounts:
        - mountPath: /etc/esp/ssl
          name:  esp-ssl
          readOnly: true
      - name: bookstore
        image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
        ports:
          - containerPort: 8000

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

例:

    spec:
      containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:2
        args: [
          "--listener_port=9000",
          "--service=bookstore.endpoints.example-project-12345.cloud.goog",
          "--rollout_strategy=managed",
          "--backend=grpc://127.0.0.1:8000"
        ]

同じ Google Cloud プロジェクトで多数のエンドポイントを実行する（100 を超える）場合は、--rollout_strategy=managed フラグを使用する代わりにコンテナのサービス構成をマウントして、Service Management API からサービス構成を pull することをおすすめします。Service Management API にはデフォルトの割り当てが存在します。多数のエンドポイントのフリートが --rollout_strategy=managed を使用している場合は、すべてのエンドポイントが最新のサービス構成をポーリングします。フリートで割り当てを超過し、サービス構成の更新に失敗する可能性もあります。以下の手順に沿ってサービス構成をマウントします。

サービス構成である JSON 構成をダウンロードします。

curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"

JSON 構成から Kubernetes 構成マップリソースを作成します。

kubectl create configmap service-config-configmap \
  --from-file=service_config.json:/tmp/service_config.json

構成マップリソースをコンテナにマウントし、フラグ「--service_config_path」を使用して構成ファイルのパスを指定します。

例:

  containers:
  - args:
    - --listener_port=8081
    - --backend=http://127.0.0.1:8080
    - --service_json_path=/etc/espv2_config/service_config.json
    - --healthz=/healthz
    image: gcr.io/endpoints-release/endpoints-runtime:2
    name: esp
    ports:
    - containerPort: 8081
      protocol: TCP
    volumeMounts:
    - mountPath: /etc/espv2_config
      name: service-config-volume
  volumes:
  - configMap:
      defaultMode: 420
      name: service-config-configmap
    name: service-config-volume

サービスを起動します。
```
kubectl create -f grpc-bookstore.yaml
```

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

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

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

外部 IP アドレスを表示します。
```
kubectl get ingress
```
EXTERNAL-IP の値をメモしておき、SERVER_IP 環境変数に保存します。この外部 IP アドレスは、リクエストをサンプル API に送信するために使用されます。
```
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

自己署名証明書のルート CA を作成します

openssl x509 -in server.crt -out client.pem -outform PEM

サンプル API にリクエストを送信します。
```
python bookstore_client.py --host SERVER_IP --port 443 \
--servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
```
- [エンドポイント] > [サービス] ページで 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

次のステップ

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

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

目標

費用

始める前に

Endpoints を構成する

Endpoints 構成をデプロイする

必要なサービスの確認

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

コンテナ クラスタの作成

コンテナ クラスタに対する kubectl の認証

必要な権限を確認する

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

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

Cloud Trace

SSL 鍵と証明書を構成する

サンプル API と ESPv2 のクラスタへのデプロイ

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

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

クリーンアップ

次のステップ

コンテナクラスタの作成

コンテナクラスタに対する `kubectl` の認証

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