拡張機能を使用したアプリケーションの例インスタンスデプロイワークフロー Amazon Linux 2 以降で動作する ECS のインスタンスデプロイのワークフロー

Elastic Beanstalk Linux プラットフォームの拡張

AWS Elastic Beanstalk Linux プラットフォームは、アプリケーションの開発と実行をサポートする多くの機能を提供します。これらの機能はすぐにご利用可能です。必要に応じて、オプションの設定、ソフトウェアのインストール、ファイルおよび起動コマンドの追加、ビルドおよび実行時の指示の提供、環境の Amazon Elastic Compute Cloud (Amazon EC2) インスタンスのさまざまなプロビジョニング段階で実行される初期化スクリプトの追加など、さまざまな方法でプラットフォームを拡張できます。

プラットフォームによっては、アプリケーションの構築または準備方法をカスタマイズしたり、アプリケーションを実行するプロセスを指定することができます。各プラットフォームのトピックでは、プラットフォームによりサポートされている場合は特に Buildfile や Procfile について言及されています。特定のプラットフォームについては、「Elastic Beanstalk プラットフォーム」を参照してください。

このページで説明されているとおり、サポートされているすべてのプラットフォームでは、構文とセマンティクスは同じです。個々のプラットフォームのトピックでは、それぞれの言語でアプリケーションを構築および実行するために、ファイルの具体的な使用方法について説明しています。

[Buildfile]

アプリケーションのカスタムビルドおよび設定コマンドを指定するには、アプリケーションソースのルートディレクトリに Buildfile という名前のファイルを配置します。ファイル名では、大文字と小文字が区別されます。Buildfile には、次の構文を使用します。


<process_name>: <command>

Buildfile 内のコマンドは、正規表現 ^[A-Za-z0-9_-]+:\s*[^\s].*$ に一致する必要があります。

Elastic Beanstalk は、Buildfile で実行されるアプリケーションをモニタリングしません。Buildfile は、短期間実行されてタスクが完了したら終了されるコマンドに使用します。長期間継続的に実行される必要のあるアプリケーションプロセスには、Procfile を使用します。

Buildfile 内のすべてのパスは、出典バンドルのルートと関連します。次の Buildfile の例では、build.sh がシェルスクリプトとして、ソースバンドルのルートに配置されています。

例 [Buildfile]


make: ./build.sh

カスタムビルドステップを提供する場合は、Buildfile ではなく、最も単純なコマンド以外の predeploy プラットフォームフックを使用することをお勧めします。プラットフォームフックは、より豊富なスクリプトとより良いエラー処理を可能にします。プラットフォームフックについては、次のセクションで説明します。

[Procfile]

アプリケーションを起動して実行するためのカスタムコマンドを指定するには、アプリケーションソースのルートディレクトリに Procfile という名前のファイルを配置します。ファイル名では、大文字と小文字が区別されます。Procfile には、次の構文を使用します。1 つまたは複数のコマンドを指定できます。


<process_name1>: <command1>
<process_name2>: <command2>
...

Procfile 内の各行は、正規表現 ^[A-Za-z0-9_-]+:\s*[^\s].*$ に一致する必要があります。

長時間継続的に実行されるアプリケーションプロセスには、Procfile を使用します。Elastic Beanstalk では、Procfile のプロセスは継続的に実行される必要があります。Elastic Beanstalk はこれらのプロセスをモニタリングし、終了されたプロセスをすべて再開します。短期間実行されるプロセスには、Buildfile コマンドを使用します。

Procfile 内のすべてのパスは、出典バンドルのルートと関連します。次の例では、Procfile は 3 つのプロセスを定義します。最初のプロセスは、この例では web と呼ばれますが、メインウェブアプリケーションです。

例 [Procfile]


web: bin/myserver
cache: bin/mycache
foo: bin/fooapp

Elastic Beanstalk は、ポート 5000 のメインウェブアプリケーションにリクエストを転送するようにプロキシサーバーを設定し、このポート番号を設定できます。Procfile の一般的な使用方法は、このポート番号をコマンド引数としてアプリケーションに渡すことです。プロキシ設定の詳細については、このページの「リバースプロキシの設定」セクションを展開します。

Elastic Beanstalk は、Procfile プロセスから標準出力ストリームとエラーストリームをログファイルにキャプチャします。Elastic Beanstalk は、プロセスの後にログファイルに名前を付け、/var/log に保存します。たとえば、前述の例では web プロセスが web-1.log および web-1.error.log についてそれぞれ stdout および stderr という名前のログを生成します。

プラットフォームフックは、環境のプラットフォームを拡張するために特別に設計されています。これらは、アプリケーションのソースコードの一部としてデプロイするカスタムスクリプトおよび他の実行可能ファイルで、Elastic Beanstalk によって、さまざまなインスタンスプロビジョニング段階で実行されます。

注記

プラットフォームフックは、Amazon Linux AMI プラットフォームのバージョン (Amazon Linux 2 より前) ではサポートされていません。

アプリケーションのデプロイプラットフォームフック

アプリケーションのデプロイは、デプロイ用の新しいソースバンドルを提供する場合、またはすべての環境インスタンスの終了および再作成が必要な設定の変更を行う場合に発生します。

アプリケーションのデプロイ中に実行されるプラットフォームフックを提供するには、ソースバンドルの .platform/hooks ディレクトリの下にある以下のサブディレクトリのいずれかにファイルを配置します。

prebuild - ファイルは、Elastic Beanstalk プラットフォームエンジンがアプリケーションソースバンドルをダウンロードして抽出した後、アプリケーションとウェブサーバーをセットアップおよび設定する前に実行されます。

prebuild ファイルは、設定ファイルの commandsセクションにあるコマンドを実行した後、および Buildfile コマンドを実行する前に実行されます。
predeploy - ここでのファイルは、Elastic Beanstalk アプリケーションとウェブサーバーをセットアップして設定した後、最終的なランタイムの場所にデプロイする前に実行されます。

predeploy ファイルは、設定ファイルの container_commandsセクションにあるコマンドを実行した後、および Procfile コマンドを実行する前に実行されます。
postdeploy - ここでのファイルは、Elastic Beanstalk プラットフォームエンジンがアプリケーションとプロキシサーバーをデプロイした後に実行されます。

これは、最後のデプロイワークフローのステップです。

設定デプロイプラットフォームフック

設定デプロイは、環境インスタンスを再作成せずに更新だけする設定変更を行った場合に発生します。次のオプションの変更は、設定を更新します。

環境プロパティとプラットフォーム固有の設定
静的ファイル
AWS X-Ray デーモン
ログストレージおよびストリーミング
アプリケーションポート (詳細については、このページのリバースプロキシの設定セクションを展開してください)

設定のデプロイ中に実行されるフックを提供するには、ソースバンドルの .platform/confighooks ディレクトリの下にフックを配置します。アプリケーションのデプロイフックと同じ 3 つのサブディレクトリが適用されます。

プラットフォームフックの詳細

フックファイルは、バイナリファイル、またはインタプリタパスを含む #! 行で始まるスクリプトファイル (#!/bin/bash など) です。すべてのファイルには、実行アクセス許可が必要です。フックファイルの実行アクセス許可を設定するために chmod +x を使用します。2022 年 4 月 29 日以降にリリースされたすべての Amazon Linux 2023 および Amazon Linux 2 ベースのプラットフォームバージョンでは、Elastic Beanstalk はすべてのプラットフォームフックスクリプトに対して実行アクセス権限を自動的に付与します。この場合、実行アクセス権限を手動で付与する必要はありません。これらのプラットフォームのバージョンのリストについては、「AWS Elastic Beanstalk リリースノートガイド」で 2022 年 4 月 29 日の Linux リリースノートを参照してください。

Elastic Beanstalk は、ファイル名の辞書順でこれらのディレクトリの各ファイルを実行します。すべてのファイルが root ユーザーとして実行されます。プラットフォームフックの現在の作業ディレクトリ (cwd) は、アプリケーションのルートディレクトリです。prebuild および predeploy ファイルの場合はアプリケーションのステージングディレクトリで、postdeploy ファイルの場合は現在のアプリケーションディレクトリです。いずれかのファイルが失敗した場合（ゼロ以外の終了コードで終了した場合）、デプロイは中止され、失敗します。

プラットフォームフックテキストスクリプトに Windows キャリッジリターン/ラインフィード (CRLF) 改行文字が含まれていると、失敗することがあります。ファイルを Windows ホストに保存してから Linux サーバーに転送した場合、ファイルには Windows CRLF の改行が含まれていることがあります。2022 年 12 月 29 日以降にリリースされたプラットフォームでは、Elastic Beanstalk でプラットフォームフックテキストファイル内の Windows CRLF 文字を Linux ラインフィード (LF) 改行文字に自動的に変換します。この日付より前にリリースされた Amazon Linux 2 プラットフォーム上でアプリケーションを実行する場合は、Windows CRLF 文字を Linux LF 文字に変換する必要があります。これを実現する方法の 1 つは、Linux ホストでスクリプトファイルを作成して保存することです。これらの文字を変換するツールはインターネットでも入手できます。

フックファイルは、アプリケーションオプションで定義したすべての環境プロパティ、およびシステム環境変数 HOME、PATH、および PORT にアクセスできます。

環境変数やその他の設定オプションの値をプラットフォームフックスクリプトに取り込むには、Elastic Beanstalk が環境インスタンスに提供する get-config ユーティリティを使用できます。詳細については、「プラットフォームスクリプトツール」を参照してください。

アプリケーションのソースコードの .ebextensions ディレクトリに設定ファイルを追加して、Elastic Beanstalk 環境のさまざまな側面を設定できます。とりわけ、設定ファイルを使用すると、環境のインスタンス上のソフトウェアやその他のファイルをカスタマイズしたり、インスタンスで初期化コマンドを実行できます。詳細については、「Linux サーバーでのソフトウェアのカスタマイズ」を参照してください。

設定ファイルを使用して、設定オプションを設定することもできます。オプションの多くはプラットフォームの動作を制御し、これらのオプションの一部はプラットフォーム固有のものです。

Amazon Linux 2 および Amazon Linux 2023 に基づくプラットフォームの場合、インスタンスをプロビジョニング中の環境インスタンスでカスタムコードを設定および実行するには、Buildfile、Procfile、およびプラットフォームフックをご使用になることをお勧めします。これらのメカニズムについては、このページの前のセクションで説明しています。.ebextensions 設定ファイルでコマンドやコンテナコマンドを使用することはできますが、操作は簡単ではありません。たとえば、YAML ファイル内にコマンドスクリプトを記述することは、構文の観点から難しい場合があります。AWS CloudFormation リソースへの参照が必要なスクリプトについては、.ebextensions 設定ファイルを使用する必要があります。

すべての Amazon Linux 2 および Amazon Linux 2023 プラットフォームのバージョンは、デフォルトのリバースプロキシサーバーとして nginx を使用します。Tomcat、Node.js、PHP、Python のプラットフォームも、代替として Apache HTTPD をサポートします。これらのプラットフォームで Apache を選択するには、aws:elasticbeanstalk:environment:proxy 名前空間の ProxyServer オプションを apache に設定します。このセクションの説明の通り、すべてのプラットフォームでプロキシサーバーの設定が一貫して有効にされています。

注記

Amazon Linux AMI プラットフォームのバージョン (Amazon Linux 2 より前) では、異なるプロキシサーバー設定にすることが必要になる場合があります。これらのレガシーの詳細は、このガイドのそれぞれのプラットフォームのトピックを参照してください。

Elastic Beanstalk は、環境のルート URL 上のメインウェブアプリケーションにウェブトラフィックを転送するように、環境のインスタンスでプロキシサーバーを設定します (例: http://my-env.elasticbeanstalk.com)。

デフォルトでは、Elastic Beanstalk はポート 80 に届くリクエストをポート 5000 のメインウェブアプリケーションに送信するようにプロキシを設定します。次の例に示すように、設定ファイルで aws:elasticbeanstalk: application: environment 名前空間を使用して PORT 環境プロパティを設定することによって、このポート番号を設定できます。


option_settings:
  - namespace:  aws:elasticbeanstalk:application:environment
    option_name:  PORT
    value:  <main_port_number>

使用しているアプリケーションの環境変数の設定の詳細については、「オプション設定」を参照してください。

アプリケーションは、プロキシで設定されているポートをリッスンする必要があります。PORT 環境プロパティを使用してデフォルトポートを変更した場合、コードは PORT 環境変数の値を読み取ることによってポートにアクセスできます。たとえば、Go の os.Getenv("PORT") または Java の System.getenv("PORT") を呼び出します。複数のアプリケーションプロセスにトラフィックを送信するようにプロキシを設定する場合、複数の環境プロパティを設定し、それらの値をプロキシ設定とアプリケーションコードの両方で使用できます。もう 1 つのオプションは、Procfile でコマンド引数としてポート値をプロセスに渡すことです。詳細については、このページの「ビルドファイルと Procfile」セクションを展開してください。

nginx の設定

Elastic Beanstalk は、デフォルトのリバースプロキシとして nginx を使用し、アプリケーションを Elastic Load Balancing ロードバランサーにマッピングします。Elastic Beanstalk は、拡張または独自の設定で完全に上書きできるデフォルトの nginx 設定を提供します。

注記

nginx .conf 設定ファイルを追加または編集するときは、必ず UTF-8 としてエンコードしてください。

Elastic Beanstalk のデフォルトの nginx 設定を拡張するには、アプリケーションソースバンドルの .platform/nginx/conf.d/ というフォルダに .conf 設定ファイルを追加します。Elastic Beanstalk の nginx 設定では、このフォルダに .conf ファイルが自動的に含められます。


~/workspace/my-app/
|-- .platform
|   `-- nginx
|       `-- conf.d
|           `-- myconf.conf
`-- other source files

Elastic Beanstalk のデフォルトの nginx 設定を完全に上書きするには、ソースバンドルの .platform/nginx/nginx.conf に設定を含めます。


~/workspace/my-app/
|-- .platform
|   `-- nginx
|       `-- nginx.conf
`-- other source files

Elastic Beanstalk の nginx 設定を上書きするには、nginx.conf に以下の行を追加することにより、拡張状態ヘルスレポートおよびモニタリング、自動アプリケーションマッピング、および静的ファイルに関して Elastic Beanstalk の設定を適用します。


 include conf.d/elasticbeanstalk/*.conf;

Apache HTTPD の設定

Tomcat、Node.js、PHP、Python のプラットフォームでは、nginx の代わりに Apache HTTPD プロキシサーバーを選択できます。これはデフォルトではありません。次の例では、Apache HTTPD が使用されるように Elastic Beanstalk を設定しています。

例 .ebextensions/httpd-proxy.config


option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: apache

追加の設定ファイルを使用して、Elastic Beanstalk のデフォルト Apache 設定を拡張できます。または、Elastic Beanstalk のデフォルトの Apache 設定を完全に上書きすることもできます。

Elastic Beanstalk のデフォルトの Apache 設定を拡張するには、アプリケーションソースバンドルの .conf というフォルダに .platform/httpd/conf.d 設定ファイルを追加します。Elastic Beanstalk の Apache 設定では、このフォルダに .conf ファイルが自動的に含められます。


~/workspace/my-app/
|-- .ebextensions
|   -- httpd-proxy.config
|-- .platform
|   -- httpd
|      -- conf.d
|         -- port5000.conf
|         -- ssl.conf
-- index.jsp

たとえば、次の Apache 2.4 設定では、ポート 5000 にリスナーを追加します。

例 .platform/httpd/conf.d/port5000.conf


listen 5000
<VirtualHost *:5000>
  <Proxy *>
    Require all granted
  </Proxy>
  ProxyPass / http://localhost:8080/ retry=0
  ProxyPassReverse / http://localhost:8080/
  ProxyPreserveHost on

  ErrorLog /var/log/httpd/elasticbeanstalk-error_log
</VirtualHost>

Elastic Beanstalk のデフォルトの Apache 設定を完全に上書きするには、ソースバンドルの .platform/httpd/conf/httpd.conf に設定を含めます。


~/workspace/my-app/
|-- .ebextensions
|   -- httpd-proxy.config
|-- .platform
|   `-- httpd
|       `-- conf
|           `-- httpd.conf
`-- index.jsp

注記

Elastic Beanstalk の Apache 設定を上書きするには、httpd.conf に以下の行を追加することにより、拡張状態ヘルスレポートおよびモニタリング、自動アプリケーションマッピング、および静的ファイルに関して Elastic Beanstalk の設定を適用します。


IncludeOptional conf.d/elasticbeanstalk/*.conf

注記

Elastic Beanstalk アプリケーションを Amazon Linux 2 または Amazon Linux 2023 プラットフォームに移行する場合は、「Elastic Beanstalk Linux アプリケーションを Amazon Linux 2023 または Amazon Linux 2 に移行する」の情報も必ずお読みください。

トピック

拡張機能を使用したアプリケーションの例
インスタンスデプロイワークフロー
Amazon Linux 2 以降で動作する ECS のインスタンスデプロイのワークフロー
プラットフォームスクリプトツール

拡張機能を使用したアプリケーションの例

以下の例は、Elastic Beanstalk Amazon Linux 2 および Amazon Linux 2023 プラットフォームでサポートされるいくつかの拡張機能 (Procfile、.ebextensions 設定ファイル、カスタムフック、およびプロキシ設定ファイル) を備えたアプリケーションソースバンドルを示しています。


~/my-app/
|-- web.jar
|-- Procfile
|-- readme.md
|-- .ebextensions/
|   |-- options.config        # Option settings
|   `-- cloudwatch.config     # Other .ebextensions sections, for example files and container commands
`-- .platform/
    |-- nginx/                # Proxy configuration
    |   |-- nginx.conf
    |   `-- conf.d/
    |       `-- custom.conf
    |-- hooks/                # Application deployment hooks
    |   |-- prebuild/
    |   |   |-- 01_set_secrets.sh
    |   |   `-- 12_update_permissions.sh
    |   |-- predeploy/
    |   |   `-- 01_some_service_stop.sh
    |   `-- postdeploy/
    |       |-- 01_set_tmp_file_permissions.sh
    |       |-- 50_run_something_after_app_deployment.sh
    |       `-- 99_some_service_start.sh
    `-- confighooks/          # Configuration deployment hooks
        |-- prebuild/
        |   `-- 01_set_secrets.sh
        |-- predeploy/
        |   `-- 01_some_service_stop.sh
        `-- postdeploy/
            |-- 01_run_something_after_config_deployment.sh
            `-- 99_some_service_start.sh

注記

これらの拡張機能のいくつかは、Amazon Linux AMI プラットフォームのバージョン (Amazon Linux 2 より前) ではサポートされていません。

インスタンスデプロイワークフロー

注記

このセクションの情報は、Amazon Linux 2 および Amazon Linux 2023 で動作する ECS プラットフォームブランチには適用されません。詳細については、次のセクション「Amazon Linux 2 以降で動作する ECS のインスタンスデプロイのワークフロー」をご覧ください。

環境のプラットフォームを拡張する方法が多数あるため、Elastic Beanstalk がインスタンスをプロビジョニングしたり、インスタンスへのデプロイを実行したりするたびに何が起こるかを知ることは有益です。次の図は、このデプロイワークフロー全体を示しています。デプロイのさまざまなフェーズと、各フェーズで Elastic Beanstalk が実行するステップを示します。

メモ

この図は、デプロイ中に環境インスタンスで Elastic Beanstalk が実行する一連のステップ全体を表しているわけではありません。この図は、カスタマイズの実行順序とコンテキストを提供するために、説明のために提供します。
簡単にするために、図では、.platform/hooks/* フックのサブディレクトリ (アプリケーションデプロイ用) のみを示しており、.platform/confighooks/* フックのサブディレクトリ (設定デプロイ用) は示していません。後者のサブディレクトリのフックは、図に示す対応するサブディレクトリのフックとまったく同じステップで実行されます。

Amazon Linux 2 プラットフォームバージョンを使用する環境内のインスタンスで拡張を実行する順序

デプロイフェーズとステップの詳細を次に示します。

最初のステップ

Elastic Beanstalk は、アプリケーションをダウンロードして抽出します。これらの各ステップの後、Elastic Beanstalk は拡張性ステップの 1 つを実行します。
1. 設定ファイルの commands: セクションにあるコマンドを実行します。
2. ソースバンドルの .platform/hooks/prebuild ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/prebuild)。
設定する

Elastic Beanstalk は、アプリケーションとプロキシサーバーを設定します。
1. ソースバンドルの Buildfile にあるコマンドを実行します。
2. ソースバンドルの .platform/nginx ディレクトリにカスタムプロキシ設定ファイルがある場合は、そのランタイムの場所にコピーします。
3. 設定ファイルの container_commands: セクションにあるコマンドを実行します。
4. ソースバンドルの .platform/hooks/predeploy ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/predeploy)。
デプロイ

Elastic Beanstalk は、アプリケーションとプロキシサーバーをデプロイして実行します。
1. ソースバンドルの Procfile ファイルにあるコマンドを実行します。
2. カスタムプロキシ設定ファイルがあれば、プロキシサーバーを実行または再実行します。
3. ソースバンドルの .platform/hooks/postdeploy ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/postdeploy)。

Amazon Linux 2 以降で動作する ECS のインスタンスデプロイのワークフロー

前のセクションでは、アプリケーションデプロイのワークフローのフェーズ全体でサポートされる拡張機能について説明します。Docker プラットフォームブランチ Amazon Linux 2 以降で動作する ECS にはいくつかの相違点があります。このセクションでは、これらの概念がこの特定のプラットフォームブランチにどのように適用されるかについて説明します。

環境のプラットフォームを拡張する方法が多数あるため、Elastic Beanstalk がインスタンスをプロビジョニングしたり、インスタンスへのデプロイを実行したりするたびに何が起こるかを知ることは有益です。次の図は、Amazon Linux 2 で動作する ECS および Amazon Linux 2023 で動作する ECS のプラットフォームブランチをベースにした環境のデプロイワークフロー全体を示しています。デプロイのさまざまなフェーズと、各フェーズで Elastic Beanstalk が実行するステップを示します。

前のセクションで説明したワークフローとは異なり、デプロイ設定フェーズでは拡張機能 (Buildfile コマンド、Procfile コマンド、リバースプロキシ設定) はサポートされていません。

メモ

この図は、デプロイ中に環境インスタンスで Elastic Beanstalk が実行する一連のステップ全体を表しているわけではありません。この図は、カスタマイズの実行順序とコンテキストを提供するために、説明のために提供します。
簡単にするために、図では、.platform/hooks/* フックのサブディレクトリ (アプリケーションデプロイ用) のみを示しており、.platform/confighooks/* フックのサブディレクトリ (設定デプロイ用) は示していません。後者のサブディレクトリのフックは、図に示す対応するサブディレクトリのフックとまったく同じステップで実行されます。

Amazon Linux 2 以降のバージョンで動作する ECS プラットフォームブランチの環境内のインスタンスで拡張機能を実行する順序

デプロイワークフローステップの詳細を次に示します。

EBhooksDir の appdeploy/pre ディレクトリにある実行可能ファイルを実行します。
ソースバンドルの .platform/hooks/prebuild ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/prebuild)。
ソースバンドルの .platform/hooks/predeploy ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/predeploy)。
EBhooksDir の appdeploy/enact ディレクトリにある実行可能ファイルを実行します。
EBhooksDir の appdeploy/post ディレクトリにある実行可能ファイルを実行します。
ソースバンドルの .platform/hooks/postdeploy ディレクトリにある実行可能ファイルを実行します (設定デプロイ用の .platform/confighooks/postdeploy)。

EBhooksDir へのリファレンスは、プラットフォームフックディレクトリのパスを表します。ディレクトリパス名を取得するには、次のように、環境インスタンスのコマンドラインで get-config スクリプトツールを実行します。


$ /opt/elasticbeanstalk/bin/get-config platformconfig -k EBhooksDir

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Linux プラットフォーム

プラットフォームスクリプトツール