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

---

OpenAPI   |  gRPC

このチュートリアルでは、Google Cloud 上ではない Kubernetes クラスタに、サンプル API と Extensible Service Proxy V2（ESPv2）を構成して、デプロイする方法を説明します。Google Kubernetes Engine（GKE）を使用する場合は、GKE での Endpoints のスタートガイドを使用します。

サンプルコードの REST API は、OpenAPI 仕様を使用して作成されています。このチュートリアルでは、API にリクエストを送信するための API キーを作成する方法も説明します。

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

• コンテナ化されたウェブ アプリケーションのデプロイ
• Kubernetes コンテナのイメージ

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

目標

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

パート 1

1. Google Cloud プロジェクトを設定します。始める前にをご覧ください。
2. チュートリアルで使用するソフトウェアをインストールして構成します。必須ソフトウェアをインストールして構成するをご覧ください。
3. 必要に応じて、サンプルコードをダウンロードします。サンプルコードを取得するをご覧ください。
4. Kubernetes 構成ファイルをダウンロードします。Kubernetes 構成ファイルを取得するをご覧ください。
5. Endpoints の構成に使用する openapi.yaml ファイルを構成します。Endpoints を構成するをご覧ください。
6. Endpoints 構成をデプロイして Cloud Endpoints サービスを作成します。Endpoints 構成をデプロイするをご覧ください。
7. Endpoints サービスの認証情報を作成します。サービスの認証情報を作成するをご覧ください。
8. API と ESPv2 をクラスタにデプロイします。API バックエンドをデプロイするをご覧ください。
9. サービスの外部 IP アドレスを取得します。外部 IP アドレスを取得するをご覧ください。
10. IP アドレスを使用して API にリクエストを送信します。IP アドレスを使用してリクエストを送信するをご覧ください。
11. API の活動を追跡します。API のアクティビティを追跡するをご覧ください。

パート 2

1. サンプル API の DNS レコードを構成します。Endpoints の DNS を構成するをご覧ください。
2. ドメイン名を使用して API にリクエストを送信します。FQDN を使用してリクエストを送信するをご覧ください。

クリーンアップ

終了したら、クリーンアップを確認して、Google Cloud アカウントに料金が発生しないようにしてください。

費用

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

• Endpoints

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

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

始める前に

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

1. 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.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

6. 後で必要になるので、Google Cloud プロジェクト ID はメモしておいてください。

必須ソフトウェアをインストールして構成する

このチュートリアルでは、Google Cloud CLI をインストールし、gcloud CLI を使用してプロジェクトを管理します。Kubernetes クラスタに対してコマンドを実行するときは、kubectl コマンドライン インターフェースを使用します。また、API をテストする手段も必要です。

必須ソフトウェアがすでにインストールされている場合は、次の手順をスキップして先に進んでください。

必須ソフトウェアをインストールして構成するには:

1. サンプル API にリクエストを送信するためのアプリケーションが必要です。

   • Linux ユーザーと MacOS ユーザーの場合: このチュートリアルでは、curl の使用例を示します。これは通常、オペレーティング システムにプリインストールされています。 curl を所有していない場合は、curl のリリースとダウンロードのページからダウンロードできます。
   • Windows ユーザーの場合: このチュートリアルでは、Invoke-WebRequest の使用例を示しています。これは PowerShell 3.0 以降でサポートされています。
2. gcloud CLI をインストールして初期化します。
3. gcloud CLI を更新し、Endpoints コンポーネントをインストールします。

   gcloud components update

4. Google Cloud CLI（gcloud）が、Google Cloud にある対象のデータとサービスへのアクセスが許可されていることを確認します。

   gcloud auth login

   表示される新しいタブで、アカウントを選択します。
5. デフォルト プロジェクトを実際のプロジェクト ID に設定します。

   gcloud config set project YOUR_PROJECT_ID

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

6. kubectl をインストールします。

   gcloud components install kubectl

7. アプリケーションのデフォルト認証情報用に使用する新しいユーザー認証情報を取得します。 ユーザー認証情報により kubectl が承認されます。

   gcloud auth application-default login

8. 表示される新しいタブでアカウントを選択します。
9. 次のコマンドを実行して、Kubernetes クライアントが正しく構成されていることを確認します。

   kubectl version

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

      Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
        GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
        BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      Server Version: version.Info{Major:"1", Minor:"7+",
        GitVersion:"v1.7.8-gke.0",
        GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
        BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      

サンプルコードをダウンロードする

必要に応じて、サンプルコードをダウンロードします。このチュートリアルでは、事前にビルドされているコンテナ イメージをデプロイします。このため、サンプルコードからコンテナをビルドする必要はありません。ただし、複数言語で提供されているサンプルコードをダウンロードすると、サンプル API の仕組みを理解できます。

サンプルコードをダウンロードするには:

Java

サンプル API をクローニングまたはダウンロードするには:

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

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

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. サンプルコードが含まれているディレクトリに移動します。

   cd java-docs-samples/endpoints/getting-started

Python

サンプル API をクローニングまたはダウンロードするには:

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

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

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. サンプルコードが含まれているディレクトリに移動します。

   cd python-docs-samples/endpoints/getting-started

Go

サンプル API をクローニングまたはダウンロードするには:

1. GOPATH 環境変数が設定されていることを確認します。
2. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. サンプルコードが含まれているディレクトリに移動します。

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

サンプル API をクローニングまたはダウンロードするには:

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

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

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. サンプルコードが含まれているディレクトリに移動します。

   cd php-docs-samples/endpoints/getting-started

Ruby

サンプル API をクローニングまたはダウンロードするには:

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

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

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. サンプルコードが含まれているディレクトリに移動します。

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

サンプル API をクローニングまたはダウンロードするには:

1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

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

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. サンプルコードが含まれているディレクトリに移動します。

   cd nodejs-docs-samples/endpoints/getting-started

Kubernetes 構成ファイルの取得

1. このチュートリアルで使用する yaml ファイルを含む GitHub リポジトリのクローンをローカルマシンに作成します。

    git clone https://github.com/googlecloudplatform/endpoints-samples

   または、zip ファイルとしてサンプルをダウンロードし、ファイルを解凍します。

2. 構成ファイルが含まれているディレクトリに移動します。

    cd endpoints-samples/kubernetes

Endpoints を構成する

サンプルコードには、OpenAPI 構成ファイル openapi.yaml が含まれています。このファイルは OpenAPI 仕様 v2.0 に準拠しています。 Endpoints を設定するには:

1. サンプルコードのディレクトリで、openapi.yaml 構成ファイルを開きます。
   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   次の点にご注意ください。

   • 上記の構成サンプルでは host フィールドの近辺に表示されている行を変更する必要があります。openapi.yaml ファイルを Endpoints にデプロイするには、完全な OpenAPI ドキュメントが必要です。
   • サンプル openapi.yaml ファイルには、このチュートリアルでは不要な認証を構成するためのセクションが含まれています。YOUR-SERVICE-ACCOUNT-EMAIL と YOUR-CLIENT-ID の行を構成する必要はありません。
   • OpenAPI は言語に依存しない仕様です。利便性を考慮し、各言語の GitHub リポジトリで、同じ openapi.yaml ファイルが getting-started サンプル内に用意されています。

2. host フィールドで、テキストを次の形式の Endpoints サービス名に置き換えます。

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

   YOUR_PROJECT_ID を Google Cloud プロジェクト ID に置き換えます。次に例を示します。

   host: "echo-api.endpoints.example-project-12345.cloud.goog"

この echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog は Endpoints サービスの名前です。これは、API にリクエストを送信するために使用する完全修飾ドメイン名（FQDN）ではありません。

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

次の構成手順をすべて完了し、IP アドレスを使用してサンプル API にリクエストを正常に送信できるようになったら、Endpoints の DNS を構成するを参照して、echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog を FQDN に構成する方法を確認してください。

Endpoints 構成をデプロイする

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

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

1. endpoints-samples/kubernetes ディレクトリ内にいることを確認します。
2. 構成をアップロードしてマネージド サービスを作成します。

   gcloud endpoints services deploy openapi.yaml
   

gcloud コマンドが Service Management API を呼び出して、openapi.yaml ファイルの host フィールドで指定した名前のマネージド サービスを作成します。Service Management は、openapi.yaml ファイル内の設定に従ってサービスを構成します。openapi.yaml に変更を加えるときは、このファイルを再デプロイして Endpoints サービスを更新する必要があります。

Service Management でサービスの作成と構成が行われるとき、情報がターミナルに出力されます。openapi.yaml ファイル内のパスが API キーを要求していないことを示す警告は無視して問題ありません。サービスの構成が完了すると、Service Management に、次のようなサービス構成 ID とサービス名を含むメッセージが表示されます。

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

上記の例では、2017-02-13r0 はサービス構成 ID、echo-api.endpoints.example-project-12345.cloud.goog は Endpoints サービスです。サービス構成 ID は、日付スタンプとそれに続くリビジョン番号で構成されます。同じ日に openapi.yaml ファイルを再度デプロイすると、サービス構成 ID のリビジョン番号が増分されます。Endpoints のサービス構成は、Google Cloud コンソールの [Endpoints] > [サービス] ページで確認できます。

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

必要なサービスの確認

Endpoints と ESP を使用するには、少なくとも次の Google サービスの有効化が必要です。

名前	タイトル
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

ほとんどの場合、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 サービスをご覧ください。

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

API を管理するには、ESP と ESPv2 のどちらにも Service Infrastructure のサービスが必要です。これらのサービスを呼び出すには、ESP と ESPv2 ではアクセス トークンを使用する必要があります。GKE、Compute Engine、App Engine フレキシブル環境などの Google Cloud 環境に ESP または ESPv2 をデプロイする場合は、ESP と ESPv2 は Google Cloud メタデータ サービスを通じてアクセス トークンを取得します。

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

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

Console

1. Google Cloud コンソールで [サービス アカウント] ページを開きます。

   [サービス アカウント] ページに移動

2. [プロジェクトの選択] をクリックします。
3. API が作成されたプロジェクトを選択し、[開く] をクリックします。
4. [+ サービス アカウントを作成] をクリックします。
5. [サービス アカウント名] 項目に、サービス アカウントの名前を入力します。
6. [作成] をクリックします。
7. [続行] をクリックします。
8. [完了] をクリックします。
9. 新しく作成したサービス アカウントのメールアドレスをクリックします。
10. [キー] をクリックします。
11. [鍵を追加]、[新しい鍵を作成] の順にクリックします。

12. [CREATE] をクリックします。JSON キーファイルがパソコンにダウンロードされます。

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

13. [閉じる] をクリックします。

gcloud

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

   gcloud projects list

2. 次のコマンドの PROJECT_ID の部分を API が含まれているプロジェクトに置き換えて、デフォルトのプロジェクトに設定します。

   gcloud config set project PROJECT_ID

   重要: API が含まれているプロジェクトと同じプロジェクト内でサービス アカウントを作成する必要があります。

3. Google Cloud CLI（gcloud）が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。

   gcloud auth login

   アカウントが複数ある場合は、API がある Google Cloud プロジェクトのアカウントを選択してください。gcloud auth list を実行すると、選択したアカウントがプロジェクトの有効なアカウントとして表示されます。

4. サービス アカウントを作成するには、次のコマンドを実行します。このとき、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

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

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

   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 バックエンドをデプロイする

ここまでの手順で OpenAPI ドキュメントを Service Management にデプロイしましたが、API バックエンドを処理するコードはまだデプロイしていません。ここでは、サンプル API と ESPv2 用の事前にビルドされたコンテナを Kubernetes にデプロイする手順を説明します。

必要な権限を確認する

クラスタに関連付けられたサービス アカウントに必要な権限を付与します。

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

詳細については、ロールと権限についてをご覧ください。

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

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

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

1. JSON ファイルの名前を service-account-creds.json に変更し、そのファイルが別のディレクトリにダウンロードされている場合は、endpoints-samples/kubernetes にコピーします。こうすると、名前が echo.yaml デプロイメント マニフェスト ファイルで指定したオプションと一致します。
2. endpoints-samples/kubernetes ディレクトリ内にいることを確認します。

3. 次のコマンドを使用して、サービス アカウントの認証情報で Kubernetes Secret を作成します。

   kubectl create secret generic service-account-creds \
      --from-file=service-account-creds.json
   

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

   secret "service-account-creds" created

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

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

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

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

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

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

1. Deployment マニフェスト ファイル echo.yaml を開き、ESPv2 起動オプションの SERVICE_NAME を、実際のサービス名に置き換えます。これは、OpenAPI ドキュメントの host フィールドで構成した名前と同じです。次に例を示します。

   "--service=echo-api.endpoints.example-project-12345.cloud.goog"

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8080",
       "--backend=127.0.0.1:8081",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--non_gcp",
       "--service_account_key=/etc/esp/creds/service-account-creds.json"
     ]
     ports:
       - containerPort: 8080
     volumeMounts:
       - mountPath: /etc/esp/creds
         name: service-account-creds
         readOnly: true
   - name: echo
     image: gcr.io/endpoints-release/echo:latest
     ports:
       - containerPort: 8081
   

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

   注: MiniKube を使用している場合は、構成ファイル内でサービス type フィールドを LoadBalancer から NodePort に変更する必要があります。
   注: 上記のコンテナ仕様の imagePullPolicy を Always に設定することをおすすめします。この設定により、新しく作成された Pod は常に ESPv2 の最新バージョンを pull することが許可されます。詳細については、構成のベスト プラクティスをご覧ください。ESPv2 の新しいバージョンがリリースされたら、すべての Pod をローリング再起動して、最新バージョンを使用できるようにします。

2. 次のコマンドを使用して、Endpoints サービスを Kubernetes にデプロイするためのサービスを開始します。

   kubectl create -f echo.yaml

   次のようなエラー メッセージが表示される場合があります。

   The connection to the server localhost:8080 was refused - did you specify the right host or port?

   これは、kubectl が正しく構成されていないことを示しています。詳しくは、kubectl の構成をご覧ください。 詳しくは、Kubernetes で Cloud Endpoints をデプロイするをご覧ください。

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

Minikube を使用している場合は、IP アドレスを使用してリクエストを送信するに進みます。 コンテナ内でサービスを開始してから外部 IP アドレスが準備できるまでには、数分かかることがあります。

サービスの外部 IP アドレスを表示するには:

1. 次のコマンドを実行します。

   kubectl get service

2. EXTERNAL-IP の値をメモします。この IP アドレスは、サンプル API にリクエストを送信するときに使用します。

IP アドレスを使用してリクエストを送信する

サンプル API がコンテナ クラスタ内で実行を始めた後、API にリクエストを送信できます。

API キーを作成し、環境変数を設定する

サンプルコードには API キーが必要です。リクエストを簡単にするために、API キーの環境変数を設定します。

1. API に使用したものと同じ Google Cloud プロジェクトの API 認証情報ページで API キーを作成します。別の Google Cloud プロジェクトで API キーを作成するには、Google Cloud プロジェクトでの API の有効化をご覧ください。

   [ドメインの確認] ページに移動

2. [認証情報を作成] をクリックして [API キー] を選択します。
3. キーをクリップボードにコピーします。
4. [閉じる] をクリックします。
5. ローカルマシンで、API キーを貼り付けて環境変数に割り当てます。
   • Linux または Mac OS の場合: export ENDPOINTS_KEY=AIza...
   • Windows PowerShell の場合: $Env:ENDPOINTS_KEY="AIza..."

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

次のコマンドでは、設定済みの ENDPOINTS_KEY 環境変数を使用します。

Linux または Mac OS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

他の Kubernetes クラスタにリクエストを送信する

Linux または Mac OS

前の手順で設定した ENDPOINTS_KEY 環境変数を使用して、curl を使用して HTTP リクエストを送信します。IP_ADDRESS をインスタンスの外部 IP アドレスに置き換えます。

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

上記の curl で:

• --data オプションは、API に送信するデータを指定します。
• --header オプションは、データが JSON 形式であることを指定します。

PowerShell

前の手順で設定した ENDPOINTS_KEY 環境変数を使用して、Invoke-WebRequest により HTTP リクエストを送信します。IP_ADDRESS をインスタンスの外部 IP アドレスに置き換えます。

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

上記の例では、最初の 2 行はバッククォートで終わります。この例を PowerShell に貼り付けるとき、バッククォートの後にスペースがないことを確認してください。このリクエスト例で使用されているオプションについては、Microsoft のドキュメントの Invoke-WebRequest をご覧ください。

サードパーティ製アプリ

Chrome ブラウザの拡張機能である Postman などのサードパーティのアプリケーションを使用してリクエストを送信できます。

• HTTP 動詞として POST を選択します。
• ヘッダーで、キー content-type とその値 application/json を選択します。
• 本文で、次のように入力します。
  {"message":"hello world"}
• URL で、環境変数ではなく実際の API キーを使用します。 例:
  http://192.0.2.0:80/echo?key=AIza...

API によって送信メッセージがエコーバックされ、次のようなレスポンスが返されます。

{
  "message": "hello world"
}

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

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

注: このチュートリアルについてのご感想やご要望がありましたら、このページの下部からフィードバックをお送りください。いただいたフィードバックは、チュートリアルの品質向上に利用させていただきます。
エラーが発生した場合は、google-cloud-endpoints Google グループに参加して、どのような問題が生じたかをお知らせください。このグループに参加すると、他の Endpoints ユーザーや、このグループをモニタリングしている Google エンジニアから回答を受け取ることができます。

API の活動を追跡する

API の活動を追跡するには:

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

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

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

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

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

Endpoints の DNS を構成する

API の Endpoints サービス名は .endpoints.YOUR_PROJECT_ID.cloud.goog ドメイン中にあるため、openapi.yaml ファイルの構成を少し変更することで、完全修飾ドメイン名（FQDN）として使用できます。このようにすると、サンプル API にリクエストを送信するときに IP アドレスの代わりに echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog を使用できます。

Endpoints DNS を構成するには:

1. OpenAPI 構成ファイルである openapi.yaml を開き、次のスニペットに示すように、ファイルの最上位レベルに x-google-endpoints プロパティを追加（インデントまたはネストさせずに）します。

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"

2. name プロパティで、YOUR_PROJECT_ID を実際のプロジェクト ID で置き換えます。
3. target プロパティで、IP_ADDRESS をサンプル API にリクエストを送信する際に使用した IP アドレスで置き換えます。
4. 更新した OpenAPI 構成ファイルを Service Management にデプロイします。

   gcloud endpoints services deploy openapi.yaml
   

たとえば、openapi.yaml ファイルは次のように構成されていると仮定します。

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

前述の gcloud コマンドで openapi.yaml ファイルをデプロイすると、Service Management はターゲット IP アドレス 192.0.2.1 に解決される DNS A レコード echo-api.endpoints.my-project-id.cloud.goog を作成します。新しい DNS 構成が反映されるまでに数分かかる場合があります。

SSL を設定する

DNS と SSL の構成方法の詳細については、Endpoints で SSL を有効にするをご覧ください。

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

サンプル API の DNS レコードが構成されたところで、FQDN（YOUR_PROJECT_ID は実際のプロジェクト ID で置き換えます）と設定済みの ENDPOINTS_KEY 環境変数を使用してサンプル API にリクエストを送信します。

• Linux または Mac OS の場合:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• Windows PowerShell の場合:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

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

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

クリーンアップ

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

• Kubernetes サービスとデプロイを削除します。

  kubectl delete -f echo.yaml

このチュートリアルで使用したサービスを停止する場合は、API と API インスタンスを削除するをご覧ください。

次のステップ

• Endpoints Google Kubernetes Engine をデプロイする方法を学習する。
• Docker イメージを作成する方法を学習する。
• API を他のデベロッパーと共有する。
• 認証について詳しく学ぶ。
• コミュニティ サポート オプションについて学習する。
• GKE デプロイのトラブルシューティングを行う。