AWS CodeDeploy
ユーザーガイド (API バージョン 2014-10-06)

AppSpec の「hooks」セクション

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

Amazon ECS のデプロイ向けの AppSpec の「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 デプロイでは、イベントフックは次の順序で実行されます。

注記

デプロイの StartInstallTestTrafficAllowTraffic、および End イベントはスクリプト化できません。このため、これらのイベントはこの図でグレーで表示されています。

'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' セクションを使用して、Lambda のデプロイを検証するために CodeDeploy が呼び出すことができる Lambda 関数を指定します。BeforeInstallAfterInstallAllowTestTrafficBeforeAllowTrafficeAllowTestTraffic デプロイライフサイクルイベントには、同じ関数または異なる関数を使用できます。検証テストが完了した後、Lambda AfterAllowTraffic 関数は CodeDeploy をコールバックし、「Succeeded」または「Failed」の結果を提供します。

重要

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

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

aws deploy put-lifecycle-event-hook-execution-status --deployment-id <deployment-id> --status Succeeded --lifecycle-event-hook-execution-id <execution-id> --region <region>

次に示すのは、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 AWS CodeDeploy. var params = { deploymentId: deploymentId, lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: 'Succeeded' // status can be 'Succeeded' or 'Failed' }; // Pass AWS 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'); } }); };

AWS Lambda のデプロイ向けの AppSpec の「hooks」セクション

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

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

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

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

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

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

注記

デプロイの StartAllowTraffic、および End イベントはスクリプト化できません。このため、これらのイベントはこの図でグレーで表示されています。

'hooks' セクションの構造

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

YAML の使用:

hooks: - BeforeAllowTraffic: BeforeAllowTrafficHookFunctionName - AfterAllowTraffic: AfterAllowTrafficHookFunctionName

JSON の使用:

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

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

「hooks」セクションを使用して、Lambda のデプロイを検証するために CodeDeploy が呼び出すことができる Lambda 関数を指定します。BeforeAllowTrafficAfterAllowTraffic デプロイライフサイクルには同じ関数または異なる関数を使用できます。検証テストが完了した後、Lambda 検証の関数は CodeDeploy をコールバックし、「Succeeded」または「Failed」の結果を提供します。

重要

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

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

aws deploy put-lifecycle-event-hook-execution-status --deployment-id <deployment-id> --status Succeeded --lifecycle-event-hook-execution-id <execution-id> --region <region>

次に示すのは、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 AWS CodeDeploy. var params = { deploymentId: deploymentId, lifecycleEventHookExecutionId: lifecycleEventHookExecutionId, status: 'Succeeded' // status can be 'Succeeded' or 'Failed' }; // Pass AWS 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'); } }); };

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

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

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

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

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

    注記

    AppSpec file は、デプロイする前にはインスタンスに存在しません。したがって、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 デプロイライフサイクルイベント中に失敗するデプロイをトラブルシューティングするには、「「UnknownError: not opened for reading」で失敗した DownloadBundle デプロイライフサイクルイベントのトラブルシューティング」を参照してください。

  • 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 をデプロイグループに指定した場合にのみ適用されます。

注記

デプロイの StartDownloadBundleInstall、および End イベントはスクリプト化できません。このため、これらのイベントはこの図でグレーで表示されています。ただし、AppSpec file の「files」セクションを編集して、Install イベント中にインストールされるものを指定できます。

Blue/Green デプロイ

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

注記

デプロイの StartDownloadBundleInstallBlockTrafficAllowTraffic、および End イベントはスクリプト化できません。このため、これらのイベントはこの図でグレーで表示されています。ただし、AppSpec file の「files」セクションを編集して、Install イベント中にインストールされるものを指定できます。

'hooks' セクションの構造

「hooks」セクションの構造は次のとおりです。

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

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

location

必須リビジョンのスクリプトファイルのバンドルでの位置。

timeout

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

注記

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

runas

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

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

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

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)。

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

以下のスクリプトは、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 のリビジョンの計画を立てる」を参照してください。