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

OpenAPI   |  gRPC

このページでは、API のバックエンド コードと Extensible Service Proxy（ESP）を Google Kubernetes Engine、Compute Engine、App Engine フレキシブル環境にデプロイする方法について説明します。

デプロイの手順は API をホストするプラットフォームによって異なりますが、どのプラットフォームの場合も必ずサービス名を ESP に提供し、オプションでデプロイ済みの最新の Cloud Endpoints サービス構成を使用するよう ESP に指定します。この情報を使用して、ESP は API の Endpoints 構成を取得できます。これにより、ESP がリクエストとレスポンスをプロキシして、Endpoints が API を管理できるようになります。

注: Extensible Service Proxy V2（ESPv2）を GKE と Kubernetes にデプロイすることもできます。ESPv2 では App Engine フレキシブル環境はサポートされていません。

要件

このページの説明は、次のことを前提としています。

• Google Cloud プロジェクトが作成されていること。
• Endpoints を構成済みであること。
• Endpoints 構成をデプロイ済みであること。

デプロイの準備

App Engine

Endpoints で管理される API をデプロイする手順は、App Engine フレキシブル環境にアプリケーションをデプロイする場合とほぼ同じですが、構成手順が少し多くなります（後述）。App Engine のドキュメントに従って、次のことを行います。

• 構成ファイルを整理します。
• app.yaml 構成ファイルを作成します。
• アプリケーションがマイクロサービスに基づいている場合は、複数のサービスアプリケーションのデプロイドキュメントで各サービスの app.yaml の構成方法を確認してください。

API を App Engine にデプロイするには、gcloud app deploy コマンドを使用します。このコマンドは、Container Builder サービスを使用してコンテナ イメージを自動的にビルドし、そのイメージを App Engine フレキシブル環境にデプロイします。

デプロイする前に:

• Google Cloud プロジェクトのオーナーが App Engine アプリケーションを作成する必要があります。
• ユーザー アカウントに必要な権限が含まれていることを確認します。

Compute Engine

Endpoints で API を管理するには、API 用のバックエンド サーバーコードと ESP をインストールして構成する必要があります。Container Registry から無料で入手できる ESP Docker イメージを実行できるようにするため、Compute Engine VM インスタンスに Docker をインストールする必要があります。

デプロイする前に:

API と ESP を Compute Engine にデプロイする前に行う必要がある手順の概要を次に示します。一般的に、Compute Engine でバックエンド サーバーコードを実行するために通常行うすべての手順を行います。

1. VM インスタンスを作成、構成、起動します。Compute Engine のドキュメントをご覧ください。
2. Docker Enterprise Edition（EE）または Docker Community Edition（CE）を VM インスタンスにインストールします。Docker のインストールをご覧ください。
3. バックエンド サーバーコード用の Docker コンテナを作成します。Cloud Build のドキュメントをご覧ください。
4. コンテナを Container Registry に push するか、または別のレジストリに push します。
5. 次のことを正常に行えることを確認します。
   • VM インスタンスに接続します。
   • Docker イメージを実行して、VM インスタンス上でバックエンド サーバーを起動します。docker run リファレンスをご覧ください。
   • リクエストを API に送信します。

GKE

Google Cloud コンソールでクラスタを作成すると、クラスタのサービス アカウントに付与される OAuth スコープに、Endpoints に必要な次のスコープがデフォルトで組み込まれます。

• Service Control: 有効
• サービス管理: 読み取り専用

gcloud container clusters create コマンド、またはサードパーティの構成ファイルを使用してクラスタを作成する場合は、次のスコープを指定していることを確認してください。

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

詳細については、アクセス スコープについてをご覧ください。

デプロイする前に:

デプロイ マニフェスト ファイルに小さなセクションを追加することで、コンテナ化されたアプリケーションとともにコンテナ クラスタ上で ESP Docker イメージを実行できます。次に、API を ESP とともに GKE にデプロイする前に行う必要があるステップの概要を説明します。一般的に、GKE でバックエンド サーバーコードを実行するために行う通常の手順をすべて行います。

1. コンテナ化されたアプリケーションをコンテナ クラスタにデプロイします。GKE のドキュメントに記載されている一般的な手順は、次のとおりです。
   1. アプリを Docker イメージにパッケージ化します。
   2. イメージをレジストリにアップロードします。
   3. コンテナ クラスタを作成します。
   4. アプリをクラスタにデプロイします。
   5. アプリをインターネットに公開します。
2. 次のことを正常に行えることを確認します。
   • API のサーバーを起動します。
   • リクエストを API に送信します。

API と ESP のデプロイ

App Engine

App Engine に API と ESP をデプロイするには:

1. API のサービス名を取得します。これは、OpenAPI ドキュメントの host フィールドで指定した名前です。
2. app.yaml ファイルを編集して、サービス名を含む endpoints_api_service というセクションを追加します。モデルとして、チュートリアルから app.yaml ファイルを使用できます。
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   ENDPOINTS-SERVICE-NAME は、API のサービス名に置き換えます。次に例を示します。

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

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

   アプリケーションがマイクロサービスに基づいている場合は、すべての app.yaml ファイルに endpoints_api_service セクションを含める必要があります。

3. app.yaml ファイルを保存します。
4. バックエンド コードと ESP を App Engine にデプロイします。

   gcloud app deploy
   

endpoints_api_service セクションを app.yaml ファイルに追加したことにより、gcloud app deploy コマンドは ESP を App Engine フレキシブル環境の別のコンテナにデプロイして構成します。すべてのリクエスト トラフィックは ESP 経由でルーティングされ、ESP はバックエンド サーバーコードを実行するコンテナとの間でリクエストとレスポンスの送受信を行います。

特定の構成 ID を使用するように ESP を構成する場合は、次の操作を行います。

1. app.yaml ファイルの endpoints_api_service セクションに、config_id フィールドを追加して、その値を特定の構成 ID に設定します。
2. rollout_strategy: managed を削除するか、rollout_strategy を fixed に設定します。fixed オプションを指定すると、config_id で指定したサービス構成を使用するように ESP が構成されます。
3. API と ESP を再デプロイします。gcloud app deploy

ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、その新しい構成の使用に際して ESP を再起動する必要があるためです。

特定の構成 ID を削除するには:

1. app.yaml ファイルから config_id オプションを削除します。
2. rollout_strategy: managed オプションを追加します。
3. gcloud app deploy コマンドを発行します。

rollout_strategy: managed オプションを使用する場合は、config_id: YOUR_SERVICE_CONFIG_ID を app.yaml ファイルに含めないでください。含めると gcloud app deploy が次のエラーで失敗します。

config_id is forbidden when rollout_strategy is set to "managed".

API を App Engine フレキシブル環境に初めてデプロイする場合、仮想マシン（VM）や他のインフラストラクチャが設定されていると、遅延が発生することがあります。詳細については、App Engine ドキュメントのデプロイの成功を確認するをご覧ください。

Compute Engine

Docker を使用して API と ESP を Compute Engine にデプロイするには:

1. VM インスタンスに接続します。INSTANCE_NAME は、実際の VM インスタンス名に置き換えます。

   gcloud compute ssh INSTANCE_NAME

2. esp_net という独自のコンテナ ネットワークを作成します。

   sudo docker network create --driver bridge esp_net

3. バックエンド サーバーコードのイメージのインスタンスを実行し、esp_net コンテナ ネットワークに接続します。

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • YOUR_API_CONTAINER_NAME はコンテナ名に置き換えます。
   • YOUR_PROJECT_ID は、イメージを push したときに使用した Google Cloud プロジェクト ID に置き換えます。
   • YOUR_IMAGE は、イメージの名前に置き換えます。
4. API のサービス名を取得します。これは、OpenAPI ドキュメントの host フィールドで指定した名前です。
5. ESP Docker イメージのインスタンスを実行します。

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • SERVICE_NAME は、実際のサービス名に置き換えます。
   • YOUR_API_CONTAINER_NAME は、API のコンテナ名に置き換えます。

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

特定の構成 ID を使用するように ESP を構成する場合は、次の操作を行います。

1. --version オプションを追加し、その値を特定の構成 ID に設定します。
2. --rollout_strategy=managed オプションを削除するか、--rollout_strategy を fixed に設定します。fixed オプションを指定すると、--version で指定したサービス構成を使用するように ESP が構成されます。
3. docker run コマンドを再度発行します。

--rollout_strategy=managed と --version の両方のオプションを指定すると、ESP は --version で指定した構成で起動しますが、その後 ESP は管理モードで実行され、最新の構成を取得します。

ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、その新しい構成の使用に際して ESP を再起動する必要があるためです。

特定の構成 ID を削除するには:

1. docker run の ESP フラグで、 --version オプションを削除します。
2. --rollout_strategy=managed オプションを追加します。
3. docker run コマンドを発行して ESP を再起動します。

ESP の起動時に指定できるオプションの完全なリストについては、ESP 起動オプションをご覧ください。

GKE

ESP を GKE にデプロイするには:

1. API のサービス名を取得します。これは、OpenAPI ドキュメントの host フィールドに指定した名前と同じです。
2. デプロイ マニフェスト ファイル（deployment.yaml ファイルとして参照されます）を開き、次のコードを containers セクションに追加します。

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed"
     ]

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

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

3. kubectl create コマンドを使用して、Kubernetes サービスを起動します。

   kubectl create -f deployment.yaml

特定の構成 ID を使用するように ESP を構成する場合は、次の操作を行います。

1. デプロイ マニフェスト ファイルに --version オプションを追加し、特定の構成 ID を設定します。
2. --rollout_strategy=managed を削除するか、--rollout_strategy を fixed に設定します。fixed オプションを指定すると、--version で指定したサービス構成を使用するように ESP が構成されます。
3. Kubernetes Service を起動します。kubectl create -f deployment.yaml

--rollout_strategy=managed と --version の両方のオプションを指定すると、ESP は --version で指定した構成で起動しますが、その後 ESP は管理モードで実行され、最新の構成を取得します。

ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、新しい構成を使用するために ESP を再起動する必要があるためです。

特定の構成 ID を削除するには:

1. デプロイ マニフェスト ファイルで、--version オプションを削除します。
2. --rollout_strategy=managed を追加します。
3. Kubernetes サービスを起動します。kubectl create -f deployment.yaml

ESP の起動時に指定できるオプションの完全なリストについては、ESP 起動オプションをご覧ください。

API の活動を追跡する

ESP と API バックエンドをデプロイした後は、curl や Postman のようなツールを使用して、API にリクエストを送信できます。正常なレスポンスが返されない場合は、レスポンス エラーのトラブルシューティングをご覧ください。

いくつかのリクエストを送信した後、次のことが可能になります。

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

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

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

• Cloud Logging ページで API のリクエスト ログを確認します。
  

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

次のステップ

• App Engine フレキシブル環境でのデプロイのトラブルシューティング
• Compute Engine での Endpoints のトラブルシューティング
• Google Kubernetes Engine での Endpoints のトラブルシューティング