app.yaml 構成ファイル

app.yaml ファイルでは、Go ランタイムの構成設定、アプリの全般設定、ネットワーク設定、その他のリソースの設定を定義します。詳細と例については、ランタイム設定の定義をご覧ください。

構文

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

# This is a comment.

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

全般設定

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

名前説明
runtime: go この設定は必須です。このアプリケーションに使用される App Engine 言語ランタイムの名前です。Go を指定するには go を使用します。デフォルトで、サポートされている最新の Go バージョンが設定されます。あるいは、サポートされているリリース バージョン(go1.10go1.9 または go1.8)を指定します。

他のランタイムも使用できます。詳しくは各言語のドキュメントをご覧ください。

env: flex フレキシブル環境を選択します。
service: service_name サービスを作成する場合は必須です。デフォルトのサービスでは省略できます。それぞれのサービスとバージョンに名前を付ける必要があります。名前には、数字、文字、ハイフンを使用できます。名前は 63 文字以下にする必要があります。また、名前の先頭または最後にハイフンは使用できません。それぞれのサービスとバージョンに一意の名前を選択する必要があります。サービスとバージョンに同じ名前を使うことはできません。

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

skip_files

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

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


skip_files:
- ^(.*/)?\.bak$

ネットワークの設定

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

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

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

オプション 説明
instance_tag その名前を持つタグが、サービスの各インスタンスが作成される際に割り当てられます。タグは、gcloud コマンドでアクションの対象をインスタンスのグループに設定するのに役立ちます。例については、compute firewalls-create コマンドの --source-tags フラグと --target-tags フラグの使用方法をご覧ください。
name フレキシブル環境のすべての VM インスタンスは、作成時に Google Compute Engine ネットワークに割り当てられます。この設定を使用して、ネットワークの名前を指定します。リソースのパスではなく、短い名前を付けます(たとえば、https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default ではなく default)。ネットワークの名前を指定しない場合、インスタンスはプロジェクトのデフォルト ネットワーク(名前は default)に割り当てられます。サブネットワーク名を指定する場合、ネットワーク名を指定する必要があります。
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)にポートを転送できます。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 Platform Console の [ネットワーキング] の [ファイアウォール ルール] ページまたは gcloud コマンドを使用して指定できます。

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

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

    network:
      forwarded_ports:
        - 2222/tcp
    
  2. GCP Console または 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 の間の偶数でなければなりません。 1 コア
memory_gb

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

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

memory_gb = cpu * [0.9 - 6.5] - 0.4

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

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

ヘルスチェック

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

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

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

  • 更新されたヘルスチェック。より細かいチェックを行います。個別のチェックを使用して、App Engine インスタンスが実行中(稼働中)であり、コンテンツを提供可能な状態(準備完了)かどうかを確認できます。ヘルスチェックは、デフォルトで有効になっています。

  • レガシー ヘルスチェック。App Engine インスタンスが実行中で正常な状態かどうかを確認します。新しい GCP プロジェクトにレガシー ヘルスチェックを使用するには、デフォルトの更新されたヘルスチェックを無効にする必要があります。

1 つのプロジェクトで使用できるヘルスチェックは 1 種類だけです。両方のタイプのヘルスチェックを変更するには、app.yaml ファイルでカスタム ロジックを使用します。

アプリケーションで使用しているヘルスチェックのタイプを確認するには、次のコマンドを実行します。

gcloud app describe

更新されたヘルスチェックが使用されている場合、説明に次の情報が含まれています。

featureSettings:
    splitHealthChecks: true

更新されたヘルスチェック

更新されたヘルスチェックには 2 つのタイプがあります。実行チェックを行うと、App Engine インスタンスの実行状況を確認できます。また、準備チェックを行うと、インスタンスがコンテンツを提供できる状態かどうかを確認できます。

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

更新されたヘルスチェックを有効にする

デフォルトでは、更新されたヘルスチェックは有効になっています。レガシー ヘルスチェックを使用している Google Cloud Platform プロジェクトに対して、更新されたヘルスチェックを有効にするには、次の手順に従います。

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

    gcloud app update --split-health-checks --project [YOUR_PROJECT_ID]

    あるいは、liveness_check または readiness_check セクションを app.yaml ファイルに指定して、更新されたヘルスチェックを有効にすることもできます。例については、実行チェック準備チェックをご覧ください。

  2. レガシー ヘルスチェックにカスタマイズした設定を使用した場合、app.yaml ファイルから health_check セクションを削除する必要があります。

  3. 新しいメジャー バージョンのアプリをデプロイし、実行状況と準備状況のヘルスチェックを開始します。

実行チェック

実行チェックでは、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 チェックの間隔(秒単位)。
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 チェックの間隔(秒単位)。
failure_threshold 2 回 1~10 この回数連続してチェックに失敗した場合、インスタンスは異常と見なされます。
success_threshold 2 回 1~10 異常なインスタンスは、この回数連続してチェックに正常に応答すると、正常に戻ります。
app_start_timeout_sec 300 秒 1~1800 この設定は、個々の VM ではなく、新しいデプロイに適用されます。この設定では、デプロイ内の十分な数のインスタンスがヘルスチェックに合格するまでに許可される最大時間を秒単位で指定します。この時間を超えると、デプロイは失敗し、ロールバックされます。タイマーは、Compute Engine インスタンスがプロビジョニングされ、ロードバランサ バックエンド サービスが作成されたときにスタートします。たとえば、十分な数のインスタンスが正常になるようにデプロイ時のタイムアウトを長くしたい場合は、この値を増やすことができます。

レガシー ヘルスチェック

レガシー ヘルスチェックのリクエストを使用するには、次のコマンドを使用して、更新されたデフォルトのヘルスチェック リクエストを事前に無効にしておく必要があります。

gcloud app update --no-split-health-checks

構成ファイルにオプションのヘルスチェック セクションを追加して、レガシー ヘルスチェックをカスタマイズできます。

health_check:
  enable_health_check: True
  check_interval_sec: 5
  timeout_sec: 4
  unhealthy_threshold: 2
  healthy_threshold: 2

レガシー ヘルスチェックでは、次のオプションを使用できます。

オプション 説明 デフォルト
enable_health_check ヘルスチェックを有効または無効にします。ヘルスチェックは、デフォルトで有効になっています。
ヘルスチェックを無効にするには、False に設定します。
True
check_interval_sec チェックの間隔。 1 秒
timeout_sec ヘルスチェックのタイムアウト間隔。 1 秒
unhealthy_threshold チェックがこの回数連続して失敗した場合、インスタンスは異常と見なされます。 1 回
healthy_threshold 異常とされたインスタンスが、この回数連続してチェックに正常に応答した場合、
インスタンスは正常な状態に戻ります。
1 回
restart_threshold ヘルスチェックがこの回数連続して失敗すると、インスタンスが再起動されます。 300 回

ヘルスチェックの頻度

高可用性を確保するため、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

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

名前 説明
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 です。

手動スケーリング

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

manual_scaling:
  instances: 5

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

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

環境変数の定義

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

env_variables:
  MY_VAR: "my value"

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

環境変数の使用

環境変数を取得して使用するには、os.Getenv を使用します。

import "os"
//...
if v := os.Getenv("MY_VAR"); v != "" {
  //...
}

上書きできないランタイム環境変数のリストもご覧ください。たとえば、GAE という接頭辞が付いた環境変数はすべてシステム用に予約されています。

プロジェクトのプロジェクト ID(アプリ ID)の設定

一部の App Engine スタンダード環境のランタイムでは、プロジェクトの app.yaml ファイルに Cloud Platform プロジェクト ID(アプリ ID)が指定されている場合があります。

フレキシブル環境では、プロジェクト ID(アプリ ID)は次のいずれかの方法で指定されます。

  • Google Cloud SDK のインストール時に gcloud init を使用する。gcloud ツールのデフォルト プロジェクト ID を表示するには、gcloud config list を実行します。
  • gcloud config set project [YOUR_PROJECT_ID] コマンドを使用して、gcloud ツールのデフォルト プロジェクト ID を設定する。
  • アプリのデプロイ時に --project フラグを使用する(例: gcloud app deploy --project [YOUR_PROJECT_ID])。
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Go の App Engine フレキシブル環境