Java アプリをデプロイする

アプリのデプロイとは、開発したアプリを App Engine にアップロードして実行することです。アプリをデプロイすると、そのアプリのバージョンと、それに対応するサービスが App Engine 内に作成されます。アプリ全体(すべてのソースコードと構成ファイルも含む)をデプロイすることも、個々のバージョンまたは構成ファイルをデプロイして更新することもできます。

プログラムによってアプリをデプロイするには、Admin API を使用します。

始める前に

アプリをデプロイする前に:

  • Cloud プロジェクトのオーナーApp Engine アプリケーションを作成する必要があります。

  • ユーザー アカウントに必要な権限が割り当てられていることを確認します。

  • プロジェクトでアプリをデプロイするための Cloud Build の権限を付与します。アプリをデプロイするときに、App Engine によって Cloud Build を使用してアプリがコンテナにビルドされ、コンテナがアプリのリージョンのランタイムにデプロイされます。Cloud Build には、デフォルトでは Java 8 アプリをデプロイする権限がないため、アプリをデプロイする前に権限を付与する必要があります。

Maven ビルドツールを使用してアプリをデプロイするには、Maven plugin for App Engine を使用するようにプロジェクトを設定する必要があります。

gcloud CLI のインストール

gcloud CLI を使用してアプリをデプロイするには、gcloud CLI をダウンロードしてインストールし、初期化する必要があります。

SDK をダウンロード

gcloud CLI がすでにインストールされ、初期化時に指定した ID とは異なる Cloud プロジェクト ID を使用する場合には、gcloud CLI 構成の管理をご覧ください。

プロキシの使用

HTTP プロキシまたは HTTPS プロキシを使用するシステムからデプロイ コマンドを実行する場合は、プロキシ経由で通信を行うようにツールを構成する必要があります。

次のコマンドを実行して gcloud CLI を構成します。

gcloud config set proxy/type [PROXY_TYPE]
gcloud config set proxy/address [PROXY_ADDRESS]
gcloud config set proxy/port [PROXY_PORT]

プロキシに usernamepassword を設定することもできます。詳細については、gcloud config をご覧ください。

アプリをデプロイする

アプリを App Engine にデプロイするには、アプリケーションのルート ディレクトリで、Maven ビルドツール(推奨)または gcloud app deploy コマンドを使用します。

Maven ビルドツールを使用してアプリをデプロイするには、pom.xml ファイルがあるプロジェクトの最上位ディレクトリから次のコマンドを実行します。

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

PROJECT_ID は実際の Cloud プロジェクトの ID に置き換えます。pom.xml ファイルですでにプロジェクト ID を指定している場合は、実行するコマンドに -Dapp.deploy.projectId プロパティを含める必要はありません。

gcloud コマンドラインの使用

  gcloud app deploy [CONFIGURATION_FILES]

[CONFIGURATION_FILES] は、1 つ以上の構成ファイルのパスに置き換えます。パス名は 1 つの空白文字で区切ります。

オプションのフラグ:

  • --version: カスタム バージョン ID を指定します。バージョン ID を指定しなかった場合は、App Engine によって生成されます。
  • --no-promote: すべてのトラフィックを自動的にそのバージョンにルーティングすることなく、アプリをデプロイします。デフォルトでは、デプロイする各バージョンが 100% のトラフィックを受信するように自動的に構成されます。
  • --project: gcloud CLI でデフォルトとして初期化されたものに代わる Cloud プロジェクト ID を指定します。

詳細については、gcloud app deploy リファレンスをご覧になるか、コマンドラインから gcloud help を実行してください。

一意のバージョン ID の選択

手動でスケーリングされるインスタンスの場合は、数値のインスタンス番号と区別するために、バージョン ID の先頭を文字にする必要があります。これによりリクエストが正しい宛先に確実にルーティングされ、URL パターンのあいまいさを回避できます。たとえば、123-dot-my-service.[REGION_ID].r.appspot.com は次の 2 通りの解釈が可能です。

  • バージョン 123 が存在する場合は、my-service サービスのバージョン 123 にリクエストをルーティングする。
  • バージョン 123 が存在しない場合は、その代わりに、my-service サービスの各バージョンが実行されているインスタンス ID 123 にリクエストをルーティングする。

ただし、自動スケーリングまたは基本スケーリングが構成されているインスタンスはターゲットにすることができないため、そのような場合はバージョンに名前を付けることができます。

複数サービス アプリケーションをデプロイする

アプリケーションが複数のサービスで構成されている場合は、対象のサービスを個別にデプロイして更新することも、すべてのサービスを同時にデプロイすることもできます。更新内容をサービスにデプロイする際は、個々の構成ファイルを更新できます。また、対応するバージョンのソースコードを更新することもできます。

たとえば、App Engine に 2 つのバージョンをデプロイして作成し、それぞれ専用のサービスで実行されるようにします。最初のバージョンをアプリのフロントエンド サービス、他方をバックエンド サービスとして機能させるとしましょう。この場合、個々の構成ファイルをデプロイすると一方のサービスの設定のみ更新できます。また、フロントエンドとバックエンドの一方または両方のソースコードを更新するために、特定のサービスの新しいバージョンをデプロイすることもできます。

複数サービスの要件

アプリケーションのサービスが複数の場合も、デプロイと更新のためのコマンドは同じですが、次の要件があります。

  • 最初にアプリのバージョンの 1 つを default サービスにデプロイする必要があります。これで、後続のサービスを作成してデプロイできるようになります。

  • 対応するバージョンの appengine-web.xml 構成ファイルにサービスの ID を指定する必要があります。サービス ID を指定するには、各構成ファイルに module: [YOUR_SERVICE_ID] 要素の定義を追加します。この要素の定義が構成ファイル内にないと、デフォルトでバージョンのデプロイ先は default サービスとなります。

  • 複数のサービスを同時にデプロイするには、対応するすべての appengine-web.xml 構成ファイルをデプロイ コマンドで指定する必要があります。default サービスを最初に指定する必要があります。

複数のサービスをデプロイするには

構成ファイルが存在するアプリケーションのルート ディレクトリから、デプロイ コマンドを実行します。その際、各サービスの appengine-web.xml ファイルの相対パスとファイル名を指定します。

Maven ビルドツールを使用する

プロジェクトのルート ディレクトリにサービスのみが含まれている場合は、すべてのサービスを 1 つの Maven コマンドでデプロイできます。

Maven のデプロイ コマンドは、プロジェクトの各サービスを繰り返し処理して、サービスの構成ファイルを見つけ、各サービスをデプロイします。

Maven プラグインを使用して複数のサービスをデプロイするには:

  1. 親の pom.xml ファイルに appengine-maven-plugin が追加されていることを確認します。
  2. 次のコマンドを実行します。

    mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

    PROJECT_ID は実際の Cloud プロジェクトの ID に置き換えます。pom.xml ファイルですでにプロジェクト ID を指定している場合は、実行するコマンドに -Dapp.deploy.projectId プロパティを含める必要はありません。

gcloud の使用

    gcloud app deploy [CONFIGURATION_FILES]

[CONFIGURATION_FILES] は、1 つ以上の構成ファイルのパスに置き換えます。パス名は 1 つの空白文字で区切ります。

各サービスが正常にデプロイされると、その確認がコマンドラインに表示されます。

ビルドログの表示

Cloud Build がストリーミングしたビルドとデプロイのログは、Cloud Console の Cloud Build 履歴セクションで確認できます。アプリのリージョンのビルドを表示するには、ページ上部の [リージョン] プルダウン メニューを使用して、フィルタするリージョンを選択します。

インデックスの更新

アプリで使用するインデックスを作成または更新するには、datastore-indexes.xml 構成ファイルを Datastore にアップロードします。この構成ファイルがアップロードされた後、まだ存在していないインデックスが作成されます。

Datastore がすべてのインデックスの作成に時間がかかることがあります。そのため、それらのインデックスは App Engine ですぐに使用できません。アプリがすでにトラフィックを受け取るように構成されている場合は、まだ作成中のインデックスを必要とするクエリに対して例外が発生する可能性があります。

例外を避けるには、次のように、すべてのインデックスを作成するための時間を確保する必要があります。

  • バージョンをデプロイする前に、index.xml 構成ファイルを Datastore にアップロードします。

    1. index.xml ファイルを Datastore にアップロードします。

      gcloud datastore indexes create index.yaml
      詳細については、gcloud datastore リファレンスをご覧ください。

    2. Cloud Console を使用して、すべてのインデックスのステータスをモニタリングします。

      [Datastore] ページに移動

    3. すべてのインデックスが作成されたら、新しいバージョンを App Engine にデプロイします。

  • トラフィックをバージョンに移行または分割する前に、インデックスを作成します。

    1. 新しいバージョン ID をアプリの appengine-web.xml ファイルの中で定義します。
    2. 新しいバージョンをデプロイします
    3. Cloud Console を使用して、すべてのインデックスのステータスをモニタリングします。

      [Datastore] ページに移動

    4. すべてのインデックスが作成されたら、Cloud Console を使用して、トラフィックをバージョンに移行または分割します。

      [バージョン] ページに移動

インデックスの詳細については、データストア インデックスの構成をご覧ください。

トラブルシューティング

発生する可能性のあるエラー メッセージのうち主なものを次に示します。

PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
必要な App Engine アプリケーションが Cloud プロジェクトに含まれていない場合、gcloud app deploy コマンドが gcloud app create コマンドを実行しようとしたときに失敗する可能性があります。App Engine アプリケーションの作成に必要な権限は、オーナーのロールを持つアカウントのみに付与されています。
Command not found
App Engine SDK(非推奨)のインストール時に dev_appserver.sh ツールのシンボリック リンクを作成しなかった場合、このツールを実行する際にツールの完全なディレクトリ パスを指定する必要があります([PATH_TO_APP_ENGINE_SDK]/dev_appserver.sh など)。
Import Error
gcloud CLI と元の App Engine SDK の両方をインストールすると、PATH へのエントリが競合してインポート エラーが発生する可能性があります。gcloud CLI コマンドの実行中にエラーが発生した場合は、元の App Engine SDK を明示的に使用してみてください。PATH で、元の App Engine SDK のエントリを前に移動すると、それらのコマンドを優先させることができます。また、完全なディレクトリ パス([PATH_TO_APP_ENGINE_SDK]/java_dev_appserver.sh)を指定してコマンドを実行することもできます。
[400] The first service (module) you upload to a new application must be the 'default' service (module)
アプリケーションの複数のサービスをデプロイして作成するには、その前に default サービスをデプロイして作成する必要があります。バージョンを default サービスにデプロイする方法については、複数のサービス アプリケーションのデプロイをご覧ください。
Too Many Versions (403)
App Engine では、アプリケーションのデプロイ済みバージョン数の上限が定められています。これは、無料アプリケーションとデプロイ済みアプリケーションとで異なります。上限に達した場合は、Cloud Console で古いバージョンを削除してから最新コードをアップロードしてください。You do not have permission to modify this app (403)
このエラーが発生するのは、認証されたアカウントに権限がないため、コマンドまたは appengine-web.xml で指定されたアプリケーション ID をデプロイできない場合です。アプリケーション ID が正しく、Cloud Console プロジェクト ID の値と一致していることを確認してください。次に、コンソールでプロジェクトの権限を確認し、アカウントがアプリのデプロイに十分な権限レベルがアカウントに付与されていることを確認してください。
[13] An internal error occurred while creating a Cloud Storage bucket.

アプリケーションと同じリージョンに、App Engine がユーザーに代わってデフォルトの Cloud Storage マルチリージョン バケットを作成します。このバケットは、アプリケーションのコンテンツを保存するために必要です。以下のシナリオで、このバケットを作成できない場合に、このエラーが返されます。

[13] An internal error occurred

このエラーは、App Engine の app.yaml 構成ファイルで vpc_access_connector キーの下に無効なリソース name が含まれている場合に発生します。サーバーレス VPC アクセス コネクタを作成する正しいプロジェクトとリージョンが name フィールドに含まれていることを確認します。

app.yaml 構成が有効なことを確認しても問題が解決しない場合は、Google Cloud SDK を使用し、--verbosity=debug フラグを追加してサービスを再デプロイします。GCP サポートに連絡して、コマンドの出力を提供します。

その他のデプロイエラー

デプロイが失敗した場合は、Cloud Build API がプロジェクトで有効になっていることを確認してください。App Engine は初めてアプリをデプロイする際、この API を自動的に有効にしますが、API を無効にした場合、デプロイが失敗します。

次のステップ