app.yaml 構成ファイル

app.yaml ファイルでは、ランタイムの構成設定や、一般的なアプリ、ネットワーク、その他のリソース設定を定義します。

.gcloudignore ファイルに app.yaml を追加しないでください。デプロイに app.yaml が必要になる場合があります。また、.gcloudignore に追加すると、デプロイが失敗します。

構文

app.yaml ファイルの構文は YAML 形式です。YAML 形式はコメントをサポートしており、ハッシュ記号（#）で始まる行は無視されます。次に例を示します。

# This is a comment.

URL とファイルパスのパターンは、要素照合とクラス照合を除き、POSIX 拡張正規表現構文を使用します。グループ化した一致への後方参照（例: \1）は、Perl 拡張（\w \W \s \S \d \D）と同様にサポートされます。

全般設定

app.yaml ファイルには、次に示す全般的な設定を記述できます。ただし、いくつかの設定は必須です。

名前説明
build_env_variables

省略可。buildpacks をサポートするランタイムを使用している場合は、app.yaml ファイルでビルド環境変数を定義できます。

詳細については、ビルド環境変数の使用をご覧ください。
runtime

必須。アプリで使用されるランタイム環境の名前です。たとえば、ランタイム環境を指定するには、次のようにします。
env: flex 必須: フレキシブル環境を選択します。
service: service_name サービスを作成する場合は必須です。デフォルトのサービスでは省略できます。それぞれのサービスとバージョンに名前を付ける必要があります。名前には、数字、文字、ハイフンを使用できます。フレキシブル環境では、VERSION-dot-SERVICE-dot-PROJECT_ID（VERSION はバージョンの名前、SERVICE はサービス名、PROJECT_ID はプロジェクト ID）全体の長さを 63 文字以下にする必要があります。また、名前の先頭や末尾にハイフンは使用できません。

サービス名を指定せずにデプロイすると、デフォルト サービスの新しいバージョンが作成されます。すでに存在するサービス名を使用してデプロイすると、そのサービスの新しいバージョンが作成されます。存在しない新しいサービス名でデプロイすると、新しいサービスとバージョンが作成されます。サービス バージョンの組み合わせごとに一意の名前を使用することをおすすめします。

注: サービスは、以前は「モジュール」と呼ばれていました。
service_account

省略可。service_account 要素を使用すると、バージョンの ID としてユーザー管理のサービス アカウントを指定できます。指定したサービス アカウントは、他の Google Cloud サービスにアクセスしてタスクを実行するときに使用されます。

サービス アカウントは、次の形式で指定する必要があります。

service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files

省略可。skip_files 要素には、アプリケーション ディレクトリ内にあるファイルのうち、App Engine にアップロードしないものを指定します。値は、1 つの正規表現か正規表現のリストです。ファイル名が正規表現と一致する場合、そのファイル名はアプリケーションがアップロードされるときに、アップロードするファイルのリストから除外されます。

たとえば、名前が .bak で終わるファイルをスキップするには、次のような skip_files セクションを追加します。

skip_files:
- ^.*\.bak$

ネットワークの設定

app.yaml 構成ファイルでは、ネットワークの設定は、たとえば次のように指定できます。

network:
  name: NETWORK_NAME
  instance_ip_mode: INSTANCE_IP_MODE
  instance_tag: TAG_NAME
  subnetwork_name: SUBNETWORK_NAME
  session_affinity: true
  forwarded_ports:
    - PORT
    - HOST_PORT:CONTAINER_PORT
    - PORT/tcp
    - HOST_PORT:CONTAINER_PORT/udp

ネットワーク設定を構成する際には、次のオプションを使用できます。

オプション 説明
name フレキシブル環境のすべての VM インスタンスは、作成時に Google Compute Engine ネットワークに割り当てられます。この設定を使用して、ネットワークの名前を指定します。リソースのパスではなく、短い名前を付けます（https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default ではなく default など）。ネットワークの名前を指定しない場合、インスタンスはプロジェクトのデフォルト ネットワーク（名前は default）に割り当てられます。サブネットワークの名前を指定する場合は、ネットワークの名前が指定されている必要があります。
instance_ip_mode 省略可。インスタンスがエフェメラル外部 IP アドレスを受信しないようにするには、internal に設定して、限定公開の Google アクセスを有効にします。以前にインスタンスがこの設定なしでデプロイされた場合、または、external に設定されてデプロイされた場合、internal に設定してインスタンスを再度デプロイすると、インスタンスからエフェメラル外部 IP アドレスが削除されます。internal 設定には制限があります。デフォルトは external です。
instance_tag 省略可。その名前を持つタグが、サービスの各インスタンスが作成される際に割り当てられます。タグは、gcloud コマンドでインスタンスのグループにアクションの対象を設定するために使用できます。例については、compute firewalls-create コマンドの --source-tags フラグと --target-tags フラグの使用方法をご覧ください。

指定しないと、共有 VPC を使用しない場合はインスタンスに aef-INSTANCE_ID のタグが付けられます。共有 VPC が使用されている場合、インスタンスには両方の aef-INSTANCE_ID and aef-instance. がタグ付けされます。
subnetwork_name 省略可。ネットワークを分割し、カスタム サブネットワークを使用できます。ネットワークの name が指定されているようにしてください。リソースのパスではなく、短い名前を付けます（https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default ではなく default など）。サブネットワークはアプリケーションと同じリージョンにある必要があります。
session_affinity 省略可。セッション中にユーザーデータをローカルに保存する場合など、特定のユーザーに関連する複数の連続したリクエストを同じ App Engine インスタンスにルーティングするように App Engine を構成するには、true に設定します。セッション アフィニティを使用すると、Cookie の値を調べて同じユーザーによる複数のリクエストを識別し、これらのリクエストをすべて同じインスタンスに送信できます。そのインスタンスが再起動された、正常でない、過負荷になった、またはインスタンス数がスケールダウンされて使用できなくなった場合、セッション アフィニティは破損し、その後のリクエストは別のインスタンスにルーティングされます。セッション アフィニティを有効にすると、ロード バランシングの設定に影響を与える可能性があります。このパラメータはデフォルトで無効になっています。
forwarded_ports 省略可。インスタンス（HOST_PORT）から Docker コンテナ（CONTAINER_PORT）にポートを転送できます。HOST_PORT は 1024～65535 の範囲で指定する必要があります。ポート 22、8080、8090、8443、10000、10001、10400～10500、11211、24231 とは競合できません。CONTAINER_PORT は 1～65535 の範囲内で指定する必要があり、22、10001、10400～10500、11211 とは競合できません。PORT のみを指定した場合、App Engine はホストとコンテナで同じポートを使用すると見なします。デフォルトでは、TCP トラフィックと UDP トラフィックの両方が転送されます。トラフィックは、appspot.com ドメインまたはカスタム ドメイン経由で送信するのではなく、ターゲット インスタンスの IP アドレスに直接送信する必要があります。

高度なネットワーク構成

Compute Engine のネットワークはサブネットワークに分割できます。これにより、VPN を有効にして、企業ネットワーク内のデータベースにアクセスできます。

App Engine アプリケーションでサブネットワークを有効にするには:

  1. カスタム サブネット ネットワークを作成します。

  2. 上記のように、ネットワーク名とサブネットワーク名を app.yaml ファイルに追加します。

  3. 静的ルーティングに基づいて簡単な VPN を確立する場合は、カスタム サブネット ネットワークにゲートウェイとトンネルを作成します。それ以外の場合は、その他の種類の VPN の作成方法をご覧ください。

ポート転送

ポート転送を行うと、インスタンス上の Docker コンテナに直接接続できます。このトラフィックはどのプロトコルでも転送されます。ポート転送は、デバッガまたはプロファイラを接続する必要がある場合に役立ちます。トラフィックは、appspot.com ドメインまたはカスタム ドメイン経由で送信するのではなく、ターゲット インスタンスの IP アドレスに直接送信する必要があります。

デフォルトでは、ネットワークの外部からの受信トラフィックは、Google Cloud Platform のファイアウォール経由では許可されません。app.yaml ファイルにポート転送を指定した後、使用するポートからのトラフィックを許可するファイアウォール ルールを追加する必要があります。

ファイアウォール ルールは、Google Cloud Console の [ネットワーキング] の [ファイアウォール ルール] ページか gcloud コマンドで指定できます。

たとえば、ポート 2222 から TCP トラフィックを転送する場合は、次のようにします。

  1. app.yaml のネットワーク設定に次の項目を追加します。

    network:
  forwarded_ports:
    - 2222/tcp

    1. Python ランタイムを使用する場合は、app.yaml を変更して以下を追加します。

      entrypoint: gunicorn -b :$PORT -b :2222 main:app

  2. Google Cloud コンソールまたは gcloud compute firewall-rules create を使用してファイアウォール ルールを指定し、すべての送信元（0.0.0.0/0）と tcp:2222 からのトラフィックを許可します。

リソースの設定

これらの設定は、コンピューティング リソースを制御します。App Engine は、指定した CPU とメモリの量に基づいて、マシンタイプを割り当てます。マシンは少なくとも指定したリソースレベルは確実に満たし、それ以上のリソースを持つこともあります。

リソースの設定では、最大 8 ボリュームの tmpfs を指定できます。tmpfs により、共有メモリを必要とするワークロードを有効化することができ、ファイル システム I/O を改善することができます。

次に例を示します。

resources:
  cpu: 2
  memory_gb: 2.3
  disk_size_gb: 10
  volumes:
  - name: ramdisk1
    volume_type: tmpfs
    size_gb: 0.5

リソースの設定を構成する際には、次のオプションを使用できます。

オプション 説明 デフォルト
cpu コアの数。1、2～32 の偶数、または 32～80 の 4 の倍数にする必要があります。 1 コア
memory_gb

RAM（GB）。アプリケーションに必要なメモリです。一部のプロセスのオーバーヘッドに必要なメモリ（最大 0.4 GB）は含まれていません。各 CPU コアには、合計で 1.0～6.5 GB のメモリが必要です。

必要なメモリの計算方法:

memory_gb = cpu * [1.0 - 6.5] - 0.4

上の例では、2 コアを指定しています。この場合、1.6～12.6 GB を要求できます。アプリケーションで使用可能なメモリの合計は、ランタイム環境で GAE_MEMORY_MB 環境変数として設定されます。

 0.6 GB
disk_size_gb GB 単位のサイズ。最小は 10 GB で、最大は 10,240 GB です。 13 GB
name ボリュームを使用する場合は必須です。ボリュームの名前です。名前は一意で、1〜63 文字にする必要があります。使用できる文字は、小文字、数字、ダッシュです。先頭文字は小文字でなければならず、最後の文字にはダッシュは使用できません。ボリュームは、アプリコンテナに /mnt/NAME としてマウントされます。
volume_type ボリュームを使用する場合は必須です。tmpfs を指定します。
size_gb ボリュームを使用する場合は必須です。ボリュームのサイズ（GB）です。最小は 0.001 GB で、最大サイズはアプリケーション コンテナと基盤となっているデバイス上で使用可能なメモリ量です。ディスク要件を満たすためにシステムに RAM が追加されることはありません。tmpft ボリュームに割り当てられる RAM の分だけ、アプリコンテナで使用できるメモリは少なくなります。精度はシステムに依存します。

スプリット ヘルスチェック

デフォルトでは、スプリット ヘルスチェックが有効になっています。定期的なヘルスチェック リクエストを使用すると、VM インスタンスが正常にデプロイされたことを確認できます。また、実行中のインスタンスが正常な状態を維持していることも確認できます。個々のヘルスチェックでは、指定された時間内にレスポンスが返される必要があります。

ヘルスチェック リクエストに対して、指定された回数連続してレスポンスがない場合、インスタンスは異常な状態と見なされます。インスタンスが実行されていない場合、再起動されます。インスタンスが準備できていない場合、クライアント リクエストは処理されません。ディスク容量に空きがない場合も、ヘルスチェックが失敗する場合があります。

次の 2 種類のヘルスチェックを使用できます。

  • 実行チェックでは、VM と Docker コンテナが実行中かどうかを確認します。App Engine は異常なインスタンスを再起動します。
  • 準備チェックでは、インスタンスが受信リクエストを処理する準備ができているかどうかを確認します。準備チェックに失敗したインスタンスは、使用可能なインスタンスのプールに追加されません。

デフォルトでは、ヘルスチェックからの HTTP リクエストはアプリケーション コンテナに転送されません。ヘルスチェックをアプリケーションにまで拡張するには、実行チェックまたは準備チェックのパスを指定します。アプリケーション用にカスタマイズされたヘルスチェックが 200 OK レスポンス コードを返した場合、正常な状態とみなされます。

実行チェック

実行チェックでは、VM と Docker コンテナが実行中かどうかを確認します。異常と見なされたインスタンスは再起動されます。

オプションの liveness_check セクションを app.yaml ファイルに追加することで、実行チェック リクエストをカスタマイズできます。次に例を示します。

liveness_check:
  path: "/liveness_check"
  check_interval_sec: 30
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2

実行チェックでは次の設定を使用できます。

項目 デフォルト 範囲（最小～最大） 説明
path なし 実行チェックをアプリケーション コンテナに転送するには、"/liveness_check" のような URL パスを指定します。
timeout_sec 4 秒 1～300 各リクエストのタイムアウト間隔（秒単位）。
check_interval_sec 30 秒 1～300 チェックの間隔（秒単位）。この値は、timeout_sec より大きな値にする必要があります。
failure_threshold 4 回 1～10 この回数連続してチェックに失敗した場合、インスタンスは異常と見なされます。
success_threshold 2 回 1～10 異常なインスタンスは、この回数連続してチェックに正常に応答すると、正常な状態に戻ります。
initial_delay_sec 300 秒 0～3600 インスタンスの開始後の遅延（秒）。この間、ヘルスチェックのレスポンスが無視されます。この設定は新しく作成された各インスタンスに適用され、新しいインスタンスが起動して実行されるまでの時間を長くすることができます。この設定は、起動プロセス中のインスタンスに対する自動修復のチェックを遅らせて、インスタンスの早すぎる再作成を防ぎます。初期遅延タイマーは、インスタンスが RUNNING モードになるとスタートします。たとえば、トラフィック処理の準備ができるまで時間がかかる初期化タスクがアプリケーションにある場合に、遅延を長くすることができます。

準備チェック

準備チェックでは、インスタンスが受信リクエストを処理できる状態かどうかを確認します。準備チェックに合格していないインスタンスは、使用可能なインスタンスのプールに追加されません。

オプションの readiness_check セクションを app.yaml ファイルに追加することで、ヘルスチェック リクエストをカスタマイズできます。次に例を示します。

readiness_check:
  path: "/readiness_check"
  check_interval_sec: 5
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2
  app_start_timeout_sec: 300

準備チェックでは次の設定を使用できます。

項目 デフォルト 範囲（最小～最大） 説明
path なし ヘルスチェックをアプリケーション コンテナに転送するには、"/readiness_check" のような URL パスを指定します。
timeout_sec 4 秒 1～300 各リクエストのタイムアウト間隔（秒単位）。
check_interval_sec 5 秒 1～300 チェックの間隔（秒単位）。この値は、timeout_sec より大きな値にする必要があります。
failure_threshold 2 回 1～10 この回数連続してチェックに失敗した場合、インスタンスは異常と見なされます。
success_threshold 2 回 1～10 異常なインスタンスは、この回数連続してチェックに正常に応答すると、正常に戻ります。
app_start_timeout_sec 300 秒 1～1800 この設定は、個々の VM ではなく、新しいデプロイに適用されます。この設定では、デプロイ内の十分な数のインスタンスがヘルスチェックに合格するまでに許される最大時間を秒単位で指定します。この時間を超えると、デプロイは失敗し、ロールバックされます。タイマーは、Compute Engine インスタンスがプロビジョニングされ、ロードバランサ バックエンド サービスが作成されたときにスタートします。たとえば、十分な数のインスタンスが正常になるようにデプロイ時のタイムアウトを長くしたい場合は、この値を増やすことができます。

ヘルスチェックの頻度

高可用性を確保するため、App Engine は個々のヘルス チェッカーの冗長コピーを作成します。失敗したヘルス チェッカーがあると、遅延なしで冗長ヘルス チェッカーが引き継ぎます。

アプリケーションの nginx.health_check ログを調べると、構成した設定より頻繁にヘルスチェックのポーリングが発生していることがあります。これは、冗長ヘルス チェッカーも設定に従うため発生します。これらの冗長ヘルス チェッカーは自動的に作成され、ユーザーが構成することはできません。

サービス スケーリング設定

サービスのスケーリングを制御するために使用されるキーは、サービスに割り当てるスケーリングのタイプによって異なります。

自動スケーリングか手動スケーリングのいずれかを使用できます。デフォルトは自動スケーリングです。

自動スケーリング

自動スケーリングは、app.yaml ファイルに automatic_scaling セクションを追加することで構成できます。次に例を示します。

automatic_scaling:
  min_num_instances: 1
  max_num_instances: 15
  cool_down_period_sec: 180
  cpu_utilization:
    target_utilization: 0.6
  target_concurrent_requests: 100

次の表には、自動スケーリングで使用できる設定が記載されています。

名前 説明
automatic_scaling 自動スケーリングはデフォルトで使用されます。なんらかの自動スケーリング設定を指定する場合は、この行を追加してください。
min_num_instances サービスに割り当てられるインスタンスの最小数。サービスがデプロイされると、この数のインスタンスが割り当てられ、トラフィックに応じてスケーリングされます。1 以上の数値にする必要があります。デフォルトは 2 で、レイテンシを抑える設定になっています。
max_num_instances サービスがスケールアップできるインスタンスの最大数。プロジェクトのインスタンスの最大数は、プロジェクトのリソース割り当てによって制限されます。デフォルトは 20 です。
cool_down_period_sec 新しいインスタンスからの情報収集を開始する前にオートスケーラーが待機する秒数。これにより、インスタンスの初期化中の情報収集を防ぐことができます。初期化中にオートスケーラーが情報を収集すると、信頼できない情報が収集されることになります。クールダウン時間は 60 秒以上にする必要があります。デフォルトは 120 です。
cpu_utilization このヘッダーは、ターゲットの CPU 使用率を指定する場合に使用します。
target_utilization ターゲットの CPU 使用率。CPU 使用率は、すべての実行中のインスタンスの平均です。CPU 使用率に基づいて、インスタンス数を増減するタイミングが決まります。処理中のリクエストに関係なく、インスタンスがシャットダウン シグナルを受信してから 25 秒後に、インスタンスがダウンスケールされます。デフォルトは 0.5 です。
target_concurrent_requests

（ベータ版）インスタンスあたりの同時接続の目標数。このパラメータに値を指定すると、オートスケーラーは、実行中のすべてのインスタンスの平均同時接続数を使用して、インスタンス数を増減するタイミングを決定します。インスタンスは、処理中のリクエストに関係なく、シャットダウン信号を受信してから 25 秒後にダウンスケールされます。

このパラメータに値を指定しないと、オートスケーラーはインスタンスごとの同時接続数を目標にしません。

接続とリクエストは異なります。接続は、クライアントが複数のリクエストを送信するために再利用できます。

手動スケーリング

手動スケーリングは、app.yaml ファイルに manual_scaling セクションを追加することで構成できます。次に例を示します。

manual_scaling:
  instances: 5

次の表は、手動スケーリングで使用できる設定を示しています。

名前説明
manual_scaling サービスの手動スケーリングを有効にするために必要です。
instances サービスに割り当てるインスタンスの数。

環境変数の定義

たとえば、次のように環境変数を app.yaml に定義すると、それをアプリで使用できます。

env_variables:
  MY_VAR: "my value"

ここで、MY_VAR と my value は定義する環境変数の名前と値です。環境変数の各エントリは、env_variables 要素の下でスペース 2 つ分インデントされています。

環境変数の使用