AppSpec 「hooks」セクション - AWS CodeDeploy

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AppSpec 「hooks」セクション

'hooks' AppSpec ファイルのセクションの内容は、デプロイのコンピューティングプラットフォームによって異なります。EC2/オンプレミスのデプロイの 'hooks' セクションには、デプロイライフサイクルイベントフックを 1 つ以上のスクリプトにリンクするマッピングが含まれます。Lambda または Amazon ECS のデプロイの 'hooks' セクションは、デプロイライフサイクルイベント中に実行する Lambda 検証の関数を指定します。イベントフックが存在しない場合、そのイベントに対してオペレーションは実行されません。このセクションは、デプロイの一部としてスクリプトまたは Lambda 検証の関数を実行する場合のみ必須です。

AppSpec Amazon ECS デプロイの「hooks」セクション

Amazon ECS のデプロイ向けのライフサイクルイベントフックのリスト

AWS Lambda フックは、ライフサイクルイベントの名前の後の新しい行に文字列で指定された 1 つの Lambda 関数です。各フックはデプロイごとに 1 回実行されます。以下は、Amazon ECS デプロイ中にフックを実行できるライフサイクルイベントの説明です。

  • BeforeInstall 置き換えタスクセットが作成される前にタスクを実行するために使用します。1 つのターゲットグループが元のタスクセットに関連付けられています。オプションのテストリスナーが指定されている場合、それは元のタスクセットに関連付けられます。この時点で、ロールバックはできません。

  • AfterInstall 置き換えタスクセットが作成され、ターゲットグループの 1 つがそれに関連付けられた後、タスクを実行するために使用します。オプションのテストリスナーが指定されている場合、それは元のタスクセットに関連付けられます。このライフサイクルイベントでのフック関数の結果により、ロールバックをトリガーできます。

  • AfterAllowTestTraffic テストリスナーが置き換えタスクセットにトラフィックを提供した後、タスクを実行するために使用します。この時点でのフック関数の結果により、ロールバックをトリガーできます。

  • BeforeAllowTraffic 2 番目のターゲットグループが置き換えタスクセットに関連付けられた後、かつ、トラフィックが置き換えタスクセットに移行される前に、タスクを実行するために使用します。このライフサイクルイベントでのフック関数の結果により、ロールバックをトリガーできます。

  • AfterAllowTraffic 2 番目のターゲットグループが置き換えタスクセットにトラフィックを提供した後、タスクを実行するために使用します。このライフサイクルイベントでのフック関数の結果により、ロールバックをトリガーできます。

詳細については、「Amazon ECS デプロイ中の処理で起こっていること」および「チュートリアル: 検証テストを使用して Amazon ECS サービスをデプロイする」を参照してください。

Amazon ECS デプロイでのフックの実行順

Amazon ECS デプロイでは、イベントフックは次の順序で実行されます。

注記

デプロイ内の [開始] TestTrafficAllowTraffic、[インストール]、[終了] の各イベントはスクリプト化できないため、この図では灰色で表示されています。

「hooks」 セクションの構造

次の例は、'hooks' セクションの構造の例を示します。

YAML の使用:

Hooks: - BeforeInstall: "BeforeInstallHookFunctionName" - AfterInstall: "AfterInstallHookFunctionName" - AfterAllowTestTraffic: "AfterAllowTestTrafficHookFunctionName" - BeforeAllowTraffic: "BeforeAllowTrafficHookFunctionName" - AfterAllowTraffic: "AfterAllowTrafficHookFunctionName"

JSON の使用:

"Hooks": [ { "BeforeInstall": "BeforeInstallHookFunctionName" }, { "AfterInstall": "AfterInstallHookFunctionName" }, { "AfterAllowTestTraffic": "AfterAllowTestTrafficHookFunctionName" }, { "BeforeAllowTraffic": "BeforeAllowTrafficHookFunctionName" }, { "AfterAllowTraffic": "AfterAllowTrafficHookFunctionName" } ] }

Lambda の「フック」関数のサンプル

'hooks'セクションを使用して、Amazon ECS CodeDeploy のデプロイを検証するために呼び出すことができる Lambda 関数を指定します。BeforeInstallAfterInstallAfterAllowTestTrafficBeforeAllowTraffic および AfterAllowTraffic のデプロイライフサイクルイベントに対して、同じ関数または別の関数を使用することもできます。検証テストが完了すると、LambdaAfterAllowTraffic CodeDeploy 関数はを呼び戻し、SucceededFailedまたはの結果を配信します。

重要

1 時間以内に Lambda 検証関数から通知されない場合、 CodeDeploy デプロイは失敗したと見なされます。

Lambda フック関数を呼び出す前に、サーバーは putLifecycleEventHookExecutionStatus コマンドを使用して、デプロイ ID およびライフサイクルイベントフック実行 ID について通知される必要があります。

次に示すのは、Node.js で記述されたサンプルの Lambda フック関数の例です。

'use strict'; const aws = require('aws-sdk'); const codedeploy = new aws.CodeDeploy({apiVersion: '2014-10-06'}); exports.handler = (event, context, callback) => { //Read the DeploymentId from the event payload. var deploymentId = event.DeploymentId; //Read the LifecycleEventHookExecutionId from the event payload var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId; /* Enter validation tests here. */ // Prepare the validation test results with the deploymentId and // the lifecycleEventHookExecutionId for CodeDeploy. var params = { deploymentId: deploymentId, lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: 'Succeeded' // status can be 'Succeeded' or 'Failed' }; // Pass CodeDeploy the prepared validation test results. codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) { if (err) { // Validation failed. callback('Validation test failed'); } else { // Validation succeeded. callback(null, 'Validation test succeeded'); } }); };

AppSpec AWSLambda デプロイの「hooks」セクション

AWS Lambda のデプロイ向けのライフサイクルイベントフックのリスト

AWS Lambda フックは、ライフサイクルイベントの名前の後の新しい行に文字列で指定された 1 つの Lambda 関数です。各フックはデプロイごとに 1 回実行されます。 AppSpec ファイルで使用できるフックの説明は次のとおりです。

  • BeforeAllowTraffic— これを使用して、トラフィックがデプロイされた Lambda 関数のバージョンに移行する前にタスクを実行します。

  • AfterAllowTraffic— これを使用して、トラフィックがデプロイされた Lambda 関数のバージョンに移行した後でタスクを実行します。

Lambda 関数のバージョンのデプロイでのフックの実行順

サーバーレスの Lambda 関数のバージョンのデプロイでは、イベントフックは次の順序で実行されます。

注記

デプロイ内の開始イベントと終了イベントはスクリプト化できないため、この図では灰色で表示されています。AllowTraffic

「hooks」 セクションの構造

次の例は、「hooks」セクションの例を示します。

YAML の使用:

hooks: - BeforeAllowTraffic: BeforeAllowTrafficHookFunctionName - AfterAllowTraffic: AfterAllowTrafficHookFunctionName

JSON の使用:

"hooks": [{ "BeforeAllowTraffic": "BeforeAllowTrafficHookFunctionName" }, { "AfterAllowTraffic": "AfterAllowTrafficHookFunctionName" }]

Lambda の「フック」関数のサンプル

「hooks」セクションを使用して、Lambda CodeDeploy のデプロイを検証するために呼び出すことができる Lambda 関数を指定します。BeforeAllowTraffic および AfterAllowTraffic デプロイライフサイクルイベントには、同じ関数または異なる関数を使用できます。検証テストが完了すると、Lambda CodeDeploy 検証関数はを呼び戻し、SucceededFailedまたはの結果を配信します。

重要

1 時間以内に Lambda 検証関数から通知されない場合、 CodeDeploy デプロイは失敗したと見なされます。

Lambda フック関数を呼び出す前に、サーバーは putLifecycleEventHookExecutionStatus コマンドを使用して、デプロイ ID およびライフサイクルイベントフック実行 ID について通知される必要があります。

次に示すのは、Node.js で記述されたサンプルの Lambda フック関数の例です。

'use strict'; const aws = require('aws-sdk'); const codedeploy = new aws.CodeDeploy({apiVersion: '2014-10-06'}); exports.handler = (event, context, callback) => { //Read the DeploymentId from the event payload. var deploymentId = event.DeploymentId; //Read the LifecycleEventHookExecutionId from the event payload var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId; /* Enter validation tests here. */ // Prepare the validation test results with the deploymentId and // the lifecycleEventHookExecutionId for CodeDeploy. var params = { deploymentId: deploymentId, lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: 'Succeeded' // status can be 'Succeeded' or 'Failed' }; // Pass CodeDeploy the prepared validation test results. codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) { if (err) { // Validation failed. callback('Validation test failed'); } else { // Validation succeeded. callback(null, 'Validation test succeeded'); } }); };

AppSpec EC2/オンプレミスデプロイの「hooks」セクション

ライフサイクルイベントフックのリスト

EC2/オンプレミスのデプロイのフックは、デプロイごとに 1 回インスタンスに対して実行されます。フックには実行するスクリプトを 1 つまたは複数指定することができます。ライフサイクルイベントの各フックは、文字列で個別の行に指定します。 AppSpec ファイルで使用できるフックの説明は次のとおりです。

デプロイおよびロールバックの種類別の有効なライフサイクルフックの詳細については、「ライフサイクルイベントフックの可用性」を参照してください。

  • ApplicationStop このデプロイライフサイクルイベントは、アプリケーションリビジョンがダウンロードされる前でも発生します。アプリケーションを適切に中止するか、現在インストールされているパッケージを削除してデプロイの準備をする場合は、このイベントのスクリプトを指定できます。 AppSpec このデプロイライフサイクルイベントに使用されたファイルとスクリプトは、前回正常にデプロイされたアプリケーションリビジョンのものです。

    注記

    AppSpec ファイルは、デプロイする前にはインスタンスに存在しません。したがって、ApplicationStop フックは、初めてインスタンスにデプロイするときは実行されません。インスタンスに 2 回目にデプロイするときは、ApplicationStop フックを使用できます。

    最後に正常にデプロイされたアプリケーションリビジョンの場所を特定するため、 CodeDeploy deployment-group-id_last_successful_installエージェントはファイルにリストされた場所を探します。このファイルは次の場所にあります。

    Amazon Linux、Ubuntu Server、RHEL Amazon EC2 インスタンスの /opt/codedeploy-agent/deployment-root/deployment-instructions フォルダ。

    Windows Server の Amazon EC2 インスタンスの C:\ProgramData\Amazon\CodeDeploy\deployment-instructions フォルダ。

    ApplicationStop デプロイライフサイクルイベント中に失敗するデプロイをトラブルシューティングするには、「失敗した ApplicationStop BeforeBlockTraffic、 AfterBlockTraffic またはデプロイライフサイクルイベントのトラブルシューティング」を参照してください。

  • DownloadBundle— このデプロイライフサイクルイベントでは、 CodeDeploy エージェントはアプリケーションリビジョンファイルを一時的な場所にコピーします。

    Amazon Linux、Ubuntu Server、RHEL Amazon EC2 インスタンスの /opt/codedeploy-agent/deployment-root/deployment-group-id/deployment-id/deployment-archive フォルダ。

    Windows Server の Amazon EC2 インスタンスの C:\ProgramData\Amazon\CodeDeploy\deployment-group-id\deployment-id\deployment-archive フォルダ。

    CodeDeploy このイベントはエージェント用に予約されていて、スクリプトを実行するために使用することはできません。

    DownloadBundle デプロイライフサイクルイベント中に失敗するデプロイをトラブルシューティングするには、「 DownloadBundle 失敗したデプロイライフサイクルイベントのトラブルシューティング UnknownError:読み取り用に開かれていません」を参照してください。

  • BeforeInstall このデプロイライフサイクルイベントは、ファイルの復号や現在のバージョンのバックアップの作成などの事前インストールタスクに使用できます。

  • Install— このデプロイライフサイクルイベントでは、 CodeDeployエージェントが一時的なロケーションからリビジョンファイルを最終的な送信先フォルダにコピーします。 CodeDeploy このイベントはエージェント用に予約されていて、スクリプトを実行するために使用することはできません。

  • AfterInstall アプリケーションの設定やファイルのアクセス許可の変更などのタスクに、このデプロイライフサイクルイベントを使用できます。

  • ApplicationStart— 通常、この導入ライフサイクルイベントを使用して、ApplicationStop実行中に停止したサービスを再開します。

  • ValidateService これが最後のデプロイライフサイクルイベントです。デプロイが正常に完了したことを確認するために使用されます。

  • BeforeBlockTraffic このデプロイライフサイクルイベントを使用して、ロードバランサーから登録解除される前のインスタンスでタスクを実行できます。

    BeforeBlockTraffic デプロイライフサイクルイベント中に失敗するデプロイをトラブルシューティングするには、「失敗した ApplicationStop BeforeBlockTraffic、 AfterBlockTraffic またはデプロイライフサイクルイベントのトラブルシューティング」を参照してください。

  • BlockTraffic このデプロイライフサイクルイベント中は、現在トラフィックの処理中であるインスタンスに対するインターネットトラフィックのアクセスがブロックされます。 CodeDeploy このイベントはエージェント用に予約されていて、スクリプトを実行するために使用することはできません。

  • AfterBlockTraffic このデプロイライフサイクルイベントを使用して、ロードバランサーから登録解除された後のインスタンスでタスクを実行できます。

    AfterBlockTraffic デプロイライフサイクルイベント中に失敗するデプロイをトラブルシューティングするには、「失敗した ApplicationStop BeforeBlockTraffic、 AfterBlockTraffic またはデプロイライフサイクルイベントのトラブルシューティング」を参照してください。

  • BeforeAllowTraffic このデプロイライフサイクルイベントを使用して、ロードバランサーに登録される前のインスタンスでタスクを実行できます。

  • AllowTraffic このデプロイライフサイクルイベント中は、デプロイ後のインスタンスに対するインターネットトラフィックのアクセスが許可されます。 CodeDeploy このイベントはエージェント用に予約されていて、スクリプトを実行するために使用することはできません。

  • AfterAllowTraffic このデプロイライフサイクルイベントを使用して、ロードバランサーに登録された後のインスタンスでタスクを実行できます。

ライフサイクルイベントフックの可用性

次の表に、各デプロイおよびロールバックシナリオで使用できるライフサイクルイベントフックを示します。

ライフサイクルイベント名 インプレースデプロイ¹ Blue/Green デプロイ: 元のインスタンス Blue/Green デプロイ: 代替インスタンス Blue/Green デプロイのロールバック: 元のインスタンス Blue/Green デプロイのロールバック: 代替インスタンス
ApplicationStop
DownloadBundle²
BeforeInstall
インストール²
AfterInstall
ApplicationStart
ValidateService
BeforeBlockTraffic
BlockTraffic²
AfterBlockTraffic
BeforeAllowTraffic
AllowTraffic²
AfterAllowTraffic

¹インプレースデプロイのロールバックにも適用されます。

² CodeDeploy オペレーション用に予約されています。スクリプトの実行には使用できません。

デプロイでのフックの実行順

インプレースデプロイ

インプレースデプロイのロールバックを含むインプレースデプロイで、イベントフックは次の順序で実行されます。

注記

インプレースデプロイの場合、トラフィックのブロックと許可に関する 6 つのフックは、 デプロイグループに Elastic Load Balancing から Classic Load Balancer、Application Load Balancer、または Network Load Balancer を指定した場合のみ適用されます。

注記

デプロイ内の [開始] DownloadBundle、[インストール]、[終了] の各イベントはスクリプト化できないため、この図では灰色で表示されています。ただし、'files' AppSpec ファイルのセクションを編集して、Install イベント中にインストールされるものを指定できます

Blue/Green デプロイ

Blue/Green デプロイでは、イベントフックは次の順序で実行されます。

注記

デプロイ内の [開始] DownloadBundleBlockTrafficAllowTraffic、[インストール]、[終了] の各イベントはスクリプト化できないため、この図では灰色で表示されています。ただし、 AppSpec ファイルの 'files' セクションを編集して、Install イベント中にインストールされるものを指定できます

「hooks」 セクションの構造

'hooks' セクションは以下の構造を持ちます。

hooks: deployment-lifecycle-event-name: - location: script-location timeout: timeout-in-seconds runas: user-name

デプロイライフサイクルイベント名の後で、次の要素を hook エントリに含めることができます。

ロケーション

必須。リビジョンのスクリプトファイルのバンドルでの位置。hooks セクションで指定するスクリプトの場所は、アプリケーションリビジョンバンドルのルートから相対的な位置です。詳細については、「CodeDeploy のリビジョンを計画する」を参照してください。

timeout

オプション。失敗と見なされる前にスクリプトの実行を許可する秒数。デフォルト値は 3600 秒 (1 時間) です。

注記

3600 秒 (1 時間) は、各デプロイライフサイクルイベントのスクリプト実行で許可される最大の時間です。スクリプトがこの制限を超過した場合、デプロイは停止し、インスタンスへのデプロイは失敗します。各デプロイライフサイクルイベントのすべてのスクリプトで、timeout に指定された合計秒数が、この制限を超えないようにします。

runas

オプション。スクリプトの実行時に偽装するユーザー。デフォルトでは、 CodeDeploy インスタンス上で実行されているエージェントです。 CodeDeploy はパスワードを保存しないため、runas ユーザーがパスワードを必要とする場合、ユーザーになりすますことはできません。この要素は、Amazon Linux、Ubuntu Server、RHEL インスタンスにのみ適用されます。

フックの環境変数の可用性

各デプロイライフサイクルイベントの間、フックスクリプトは次の環境変数にアクセスできます。

APPLICATION_NAME

現在のデプロイの一部である CodeDeploy 、アプリケーションの名前 (などWordPress_App)。

DEPLOYMENT_ID

この ID CodeDeploy は、現在のデプロイに割り当てられています (例:d-AB1CDEF23)。

DEPLOYMENT_GROUP_NAME

CodeDeploy 現在のデプロイの一部であるデプロイグループの名前 (などWordPress_DepGroup)。

DEPLOYMENT_GROUP_ID

CodeDeploy 現在のデプロイの一部であるデプロイグループの ID。b1a2189b-dd90-4ef5-8f40-4c1c5EXAMPLE

LIFECYCLE_EVENT

現在のデプロイライフサイクルイベントの名前 (例: AfterInstall)。

これらの環境変数は各デプロイライフサイクルイベントにローカルです。

デプロイバンドルのソースによっては、スクリプトをフックできる環境変数が他にもあります。

Amazon S3 からのバンドル

  • BUCKET

    デプロイバンドルのダウンロード元の Amazon S3 バケットの名前 (などmy-s3-bucket)。

  • BUNDLE_KEY

    Amazon S3 バケット内のダウンロード済みバンドルのオブジェクトキー (例:WordPress_App.zip)。

  • バンドル_バージョン

    バンドルのオブジェクトバージョン (例:3sL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo)。この変数は、Amazon S3 バケットでオブジェクトのバージョニングが有効になっている場合にのみ設定されます

  • BUNDLE_ETAG

    バンドルのオブジェクト etag (例:b10a8db164e0754105b7a99be72e3fe5-4)。

バンドルから GitHub

  • BUNDLE_COMMIT

    Git によって生成されたバンドルのSHA256コミットハッシュ (例:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26)。

以下のスクリプトは、DEPLOYMENT_GROUP_NAME の値が Staging と等しい場合に、Apache HTTP サーバーでリッスンするポートを 80 ではなく 9090 に変更します。このスクリプトは BeforeInstall デプロイライフサイクルイベント中に呼び出される必要があります。

if [ "$DEPLOYMENT_GROUP_NAME" == "Staging" ] then sed -i -e 's/Listen 80/Listen 9090/g' /etc/httpd/conf/httpd.conf fi

次のスクリプトの例では、DEPLOYMENT_GROUP_NAME 環境変数の値が Staging に等しい場合に、エラーログに記録されるメッセージの詳細レベルを警告からデバッグに変更します。このスクリプトは BeforeInstall デプロイライフサイクルイベント中に呼び出される必要があります。

if [ "$DEPLOYMENT_GROUP_NAME" == "Staging" ] then sed -i -e 's/LogLevel warn/LogLevel debug/g' /etc/httpd/conf/httpd.conf fi

以下のスクリプトの例では、指定されたウェブページを、これらの環境変数の値を表示するテキストで置き換えます。このスクリプトは AfterInstall デプロイライフサイクルイベント中に呼び出される必要があります。

#!/usr/bin/python import os strToSearch="<h2>This application was deployed using CodeDeploy.</h2>" strToReplace="<h2>This page for "+os.environ['APPLICATION_NAME']+" application and "+os.environ['DEPLOYMENT_GROUP_NAME']+" deployment group with "+os.environ['DEPLOYMENT_GROUP_ID']+" deployment group ID was generated by a "+os.environ['LIFECYCLE_EVENT']+" script during "+os.environ['DEPLOYMENT_ID']+" deployment.</h2>" fp=open("/var/www/html/index.html","r") buffer=fp.read() fp.close() fp=open("/var/www/html/index.html","w") fp.write(buffer.replace(strToSearch,strToReplace)) fp.close()

hooks の例

hooks エントリの例を次に示します。AfterInstall ライフサイクルイベントに 2 つのフックを指定しています。

hooks: AfterInstall: - location: Scripts/RunResourceTests.sh timeout: 180 - location: Scripts/PostDeploy.sh timeout: 180

デプロイプロセスの AfterInstall ステージ中に、Scripts/RunResourceTests.sh スクリプトが実行されます。スクリプトの実行に 180 秒 (3 分) 以上かかる場合、デプロイは成功しません。

「hooks」セクションで指定するスクリプトの場所は、アプリケーションリビジョンバンドルのルートに相対的な位置です。前述の例では、RunResourceTests.sh という名前のファイルが Scripts という名前のディレクトリにあります。Scripts ディレクトリはバンドルのルートレベルにあります。詳細については、「CodeDeploy のリビジョンを計画する」を参照してください。