このページでは、API のバックエンド コードと Extensible Service Proxy(ESP)を Google Kubernetes Engine、Compute Engine、App Engine フレキシブル環境にデプロイする方法について説明します。
デプロイの手順は API をホストするプラットフォームによって異なりますが、どのプラットフォームの場合も必ずサービス名を ESP に提供し、オプションでデプロイ済みの最新の Cloud Endpoints サービス構成を使用するよう ESP に指定します。この情報を使用して、ESP は API の Endpoints 構成を取得できます。これにより、ESP がリクエストとレスポンスをプロキシして、Endpoints が API を管理できるようになります。
要件
このページの説明は、次のことを前提としています。
デプロイの準備
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 でバックエンド サーバーコードを実行するために通常行うすべての手順を行います。
- VM インスタンスを作成、構成、起動します。Compute Engine のドキュメントをご覧ください。
- Docker Enterprise Edition(EE)または Docker Community Edition(CE)を VM インスタンスにインストールします。Docker のインストールをご覧ください。
- バックエンド サーバーコード用の Docker コンテナを作成します。Cloud Build のドキュメントをご覧ください。
- コンテナを Container Registry に push するか、または別のレジストリに push します。
- 次のことを正常に行えることを確認します。
- 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 でバックエンド サーバーコードを実行するために行う通常の手順をすべて行います。
- コンテナ化されたアプリケーションをコンテナ クラスタにデプロイします。GKE のドキュメントに記載されている一般的な手順は、次のとおりです。
- アプリを Docker イメージにパッケージ化します。
- イメージをレジストリにアップロードします。
- コンテナ クラスタを作成します。
- アプリをクラスタにデプロイします。
- アプリをインターネットに公開します。
- 次のことを正常に行えることを確認します。
- API のサーバーを起動します。
- リクエストを API に送信します。
API と ESP のデプロイ
App Engine
App Engine に API と ESP をデプロイするには:
- API のサービス名を取得します。これは、OpenAPI ドキュメントの
host
フィールドで指定した名前です。 app.yaml
ファイルを編集して、サービス名を含むendpoints_api_service
というセクションを追加します。モデルとして、チュートリアルからapp.yaml
ファイルを使用できます。Java Python Go PHP Ruby NodeJS 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
セクションを含める必要があります。app.yaml
ファイルを保存します。- バックエンド コードと ESP を App Engine にデプロイします。
gcloud app deploy
endpoints_api_service
セクションを app.yaml
ファイルに追加したことにより、gcloud app deploy
コマンドは ESP を App Engine フレキシブル環境の別のコンテナにデプロイして構成します。すべてのリクエスト トラフィックは ESP 経由でルーティングされ、ESP はバックエンド サーバーコードを実行するコンテナとの間でリクエストとレスポンスの送受信を行います。
特定の構成 ID を使用するように ESP を構成する場合は、次の操作を行います。
app.yaml
ファイルのendpoints_api_service
セクションに、config_id
フィールドを追加して、その値を特定の構成 ID に設定します。rollout_strategy: managed
を削除するか、rollout_strategy
をfixed
に設定します。fixed
オプションを指定すると、config_id
で指定したサービス構成を使用するように ESP が構成されます。- API と ESP を再デプロイします。
gcloud app deploy
ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、その新しい構成の使用に際して ESP を再起動する必要があるためです。
特定の構成 ID を削除するには:
app.yaml
ファイルからconfig_id
オプションを削除します。rollout_strategy: managed
オプションを追加します。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 にデプロイするには:
- VM インスタンスに接続します。
INSTANCE_NAME
は、実際の VM インスタンス名に置き換えます。gcloud compute ssh INSTANCE_NAME
esp_net
という独自のコンテナ ネットワークを作成します。sudo docker network create --driver bridge esp_net
- バックエンド サーバーコードのイメージのインスタンスを実行し、
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
は、イメージの名前に置き換えます。
- API のサービス名を取得します。これは、OpenAPI ドキュメントの
host
フィールドで指定した名前です。 - 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 を構成する場合は、次の操作を行います。
--version
オプションを追加し、その値を特定の構成 ID に設定します。--rollout_strategy=managed
オプションを削除するか、--rollout_strategy
をfixed
に設定します。fixed
オプションを指定すると、--version
で指定したサービス構成を使用するように ESP が構成されます。docker run
コマンドを再度発行します。
--rollout_strategy=managed
と --version
の両方のオプションを指定すると、ESP は --version
で指定した構成で起動しますが、その後 ESP は管理モードで実行され、最新の構成を取得します。
ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、その新しい構成の使用に際して ESP を再起動する必要があるためです。
特定の構成 ID を削除するには:
docker run
の ESP フラグで、--version
オプションを削除します。--rollout_strategy=managed
オプションを追加します。docker run
コマンドを発行して ESP を再起動します。
ESP の起動時に指定できるオプションの完全なリストについては、ESP 起動オプションをご覧ください。
GKE
ESP を GKE にデプロイするには:
- API のサービス名を取得します。これは、OpenAPI ドキュメントの
host
フィールドに指定した名前と同じです。 - デプロイ マニフェスト ファイル(
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 でなく、このオプションを使用するようにしてください。 - kubectl create コマンドを使用して、Kubernetes サービスを起動します。
kubectl create -f deployment.yaml
特定の構成 ID を使用するように ESP を構成する場合は、次の操作を行います。
- デプロイ マニフェスト ファイルに
--version
オプションを追加し、特定の構成 ID を設定します。 --rollout_strategy=managed
を削除するか、--rollout_strategy
をfixed
に設定します。fixed
オプションを指定すると、--version
で指定したサービス構成を使用するように ESP が構成されます。- Kubernetes Service を起動します。
kubectl create -f deployment.yaml
--rollout_strategy=managed
と --version
の両方のオプションを指定すると、ESP は --version
で指定した構成で起動しますが、その後 ESP は管理モードで実行され、最新の構成を取得します。
ESP が特定の構成 ID をあまり長期間使用しないようにすることをおすすめします。これは、更新したサービス構成をデプロイするときに、新しい構成を使用するために ESP を再起動する必要があるためです。
特定の構成 ID を削除するには:
- デプロイ マニフェスト ファイルで、
--version
オプションを削除します。 --rollout_strategy=managed
を追加します。- Kubernetes サービスを起動します。
kubectl create -f deployment.yaml
ESP の起動時に指定できるオプションの完全なリストについては、ESP 起動オプションをご覧ください。
API の活動を追跡する
ESP と API バックエンドをデプロイした後は、curl
や Postman のようなツールを使用して、API にリクエストを送信できます。正常なレスポンスが返されない場合は、レスポンス エラーのトラブルシューティングをご覧ください。
いくつかのリクエストを送信した後、次のことが可能になります。
[エンドポイント] > [サービス] で API のアクティビティ グラフを表示します。
グラフにリクエストが反映されるまでに、しばらく時間がかかる場合があります。Cloud Logging ページで API のリクエスト ログを確認します。
次のステップ
- App Engine フレキシブル環境でのデプロイのトラブルシューティング
- Compute Engine での Endpoints のトラブルシューティング
- Google Kubernetes Engine での Endpoints のトラブルシューティング