# Amazon ECS サービスデプロイの Lambda フック
Lambda フックは、Amazon ECS がデプロイの特定の段階で呼び出す Lambda 関数です。デプロイが進む前に、フックを使用して、検証テストの実行、ガバナンスポリシーの適用、カスタムロジックの実装を行うことができます。
Amazon ECS がフックを呼び出すと、関数が `hookStatus` フィールドを含む JSON オブジェクトを返す必要があります。必要に応じて、再試行のタイミングを制御するための `callBackDelay` と、呼び出し間でデータを渡すための `hookDetails` を含めることができます。関数が有効な `hookStatus` を返さない場合、または失敗した場合、Amazon ECS はデプロイをロールバックします。
## hookStatus 値
有効な `hookStatus` 値を次に示します。
+ `SUCCEEDED` – デプロイは次のライフサイクルステージへと進みます。
+ `FAILED` – Amazon ECS は最後に成功したサービスリビジョンにデプロイをロールバックします。
+ `IN_PROGRESS` – Amazon ECS は遅延後に関数を再度呼び出します。遅延のデフォルト値は 30 秒です。この値は、`hookStatus` とともに `callBackDelay` を返すことでカスタマイズできます。
次の例では、カスタムコールバックの遅延を使用して `hookStatus` を返す方法が示されます。この例では、Amazon ECS によってこのフックはデフォルトの 30 秒ではなく 60 秒後に再試行されます。
```
{
"hookStatus": "IN_PROGRESS",
"callBackDelay": 60
}
```
## hookDetails を使用した状態の受け渡し
`hookDetails` フィールドは、ライフサイクルフック関数にデータを渡すために使用できるディクショナリです。`hookDetails` の入力方法は次の 2 つです。
+ **サービスの作成時または更新時** – サービス定義内のライフサイクルフック設定で `hookDetails` を定義します。Amazon ECS は、呼び出しのたびにこのデータを関数に渡します。これを使用して、サービス固有の設定を渡すことで、フックを複数のサービス間で再利用できるようにします。
+ **IN\_PROGRESS レスポンスによるランタイム時** – フックステータス `IN_PROGRESS` とともに `hookDetails` を返します。Amazon ECS は、次の呼び出し時にこのデータを関数に返します。これを使用して、外部ストレージのない呼び出し間の状態を維持します。
次の例は、S3 バケット名を関数に渡すサービス定義のライフサイクルフック設定を示しています。
```
{
"hookTargetArn": "arn:aws:lambda:us-west-2:123456789012:function:my-approval-hook",
"roleArn": "arn:aws:iam::123456789012:role/ecs-lambda-invoke-role",
"lifecycleStages": [
"POST_TEST_TRAFFIC_SHIFT"
],
"hookDetails": {
"S3_BUCKET_NAME": "my-approval-bucket"
}
}
```
関数が `IN_PROGRESS` を返すと、レスポンスに `hookDetails` を含めることもできます。Amazon ECS はこのデータをマージし、次の呼び出し時に返します。一般的なユースケースには、呼び出し間で外部リソースのメトリクスカウンターまたは ARNs を渡すことが含まれます。
```
{
"hookStatus": "IN_PROGRESS",
"callBackDelay": 30,
"hookDetails": {
"approvalChecked": true,
"S3_BUCKET_NAME": "my-approval-bucket"
}
}
```
Amazon ECS は次の呼び出しで `executionDetails` とともにイベントペイロードに `hookDetails` を含めます。
```
{
"executionId": "e8d5a28f-eb01-4f3c-9454-a30ba6dc54bc",
"lifecycleStage": "POST_TEST_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {}
},
"hookDetails": {
"approvalChecked": true,
"S3_BUCKET_NAME": "my-approval-bucket"
}
}
```
関数は `event["hookDetails"]` を読み取り、以前の呼び出しの設定と状態にアクセスできます。
**注記**
ランタイム時に `hookDetails` に追加されたデータは、1 つのデプロイ内の同じフックの呼び出し間でのみ保持されます。データは、同じデプロイ内の異なるフック間や、異なるデプロイ内の同じフック間で引き継がれることはありません。
## タイムアウト設定
`timeoutConfiguration` を使用して Lambda フックのタイムアウトを設定できます。Lambda 関数がタイムアウトの有効期限が切れる前に `SUCCEEDED` または `FAILED` を返さない場合、Amazon ECS は設定されたタイムアウトアクションを実行します。
| フィールド | 説明 |
| --- | --- |
| timeoutConfiguration.timeoutInMinutes | 待機時間。有効な範囲: 1～1,440 分 (24 時間)。デフォルト: 1,440 分。 |
| timeoutConfiguration.action | タイムアウトが期限切れになった場合に実行するアクション。有効な値: ROLLBACK、CONTINUE。デフォルト: ROLLBACK。 |
## サポートされているライフサイクルステージ
Lambda フックは、次のライフサイクルステージで設定できます。
+ `RECONCILE_SERVICE`
+ `PRE_SCALE_UP`
+ `POST_SCALE_UP`
+ `TEST_TRAFFIC_SHIFT`
+ `POST_TEST_TRAFFIC_SHIFT`
+ `PRE_PRODUCTION_TRAFFIC_SHIFT`
+ `PRODUCTION_TRAFFIC_SHIFT`
+ `POST_PRODUCTION_TRAFFIC_SHIFT`
線形デプロイとカナリアデプロイの場合、`PRODUCTION_TRAFFIC_SHIFT` または `PRE_PRODUCTION_TRAFFIC_SHIFT` に設定された Lambda フックは、トラフィックシフトの各ステップで呼び出されます。
ライフサイクルステージのカテゴリの詳細については、「[Amazon ECS サービスデプロイのライフサイクルフック](deployment-lifecycle-hooks.md)」を参照してください。
## ライフサイクルペイロード
### 一般的なペイロード構造
Amazon ECS がライフサイクルフック Lambda 関数を呼び出すと、イベントペイロードに次の最上位フィールドが含まれます。
+ `executionId` – このフック実行の一意の識別子。
+ `lifecycleStage` – 現在のライフサイクルステージ (`PRODUCTION_TRAFFIC_SHIFT` など)。
+ `resourceArn` – デプロイに関連付けられたリソースの ARN。
+ `executionDetails` – 次のリストで説明されているデプロイ固有の情報を含むオブジェクト。
`executionDetails` オブジェクトには、以下のフィールドが含まれています。
+ `serviceArn` – サービスの Amazon リソースネーム (ARN)。
+ `targetServiceRevisionArn` – デプロイされるターゲットサービスリビジョンの ARN。
+ `testTrafficWeights` – サービスリビジョン ARN が対応するテストトラフィックの重みの割合を示すマップ。
+ `productionTrafficWeights` – サービスリビジョン ARN が対応する本番トラフィックの重みの割合を示すマップ。
次の例は、Lambda 関数が受け取る完全なイベント構造を示しています。
```
{
"executionId": "f4fcae0f-9bec-41c6-ba87-0eaa0cef8af5",
"lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
}
}
}
```
### ライフサイクルステージペイロード
後のセクションで、各ライフサイクルステージのペイロードの例を示しています。これらの例では、グリーンサービスリビジョン (`9313423515462893900`) はデプロイされている新しいリビジョンであり、ブルーサービスリビジョン (`1920498462936580504`) は既存の本番用リビジョンです。
#### PRE\_SCALE\_UP
このステージは、Amazon ECS がグリーンサービスリビジョンタスクを起動する前に発生します。グリーンサービスリビジョンは開始されておらず、トラフィックはルーティングされません。
```
{
"executionId": "e8d5a28f-eb01-4f3c-9454-a30ba6dc54bc",
"lifecycleStage": "PRE_SCALE_UP",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {}
}
}
```
#### POST\_SCALE\_UP
このステージは、Amazon ECS がグリーンサービスリビジョンタスクを起動し、それらが正常になったら発生します。グリーンタスクは実行中ですが、まだトラフィックを受信していません。
```
{
"executionId": "8b095b05-7bb0-4c56-a223-a3f61f4f9295",
"lifecycleStage": "POST_SCALE_UP",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {}
}
}
```
#### TEST\_TRAFFIC\_SHIFT
このステージは、Amazon ECS がテストトラフィックをグリーンサービスリビジョンにシフトさせるときに発生します。`testTrafficWeights` は、グリーンリビジョンがテストトラフィックを 100% 受信する一方で、ブルーリビジョンは受信しない (0%) ことを示しています。本番トラフィックは引き続きブルーリビジョンに流れます。
```
{
"executionId": "779085de-ab47-42bc-84ad-41f9914a8643",
"lifecycleStage": "TEST_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
},
"productionTrafficWeights": {}
}
}
```
#### POST\_TEST\_TRAFFIC\_SHIFT
このステージは、Amazon ECS がテストトラフィックシフトを完了した後に発生します。グリーンサービスリビジョンにより、テストトラフィックの 100% が処理されます。
```
{
"executionId": "3a0345ba-b029-404b-890d-7da2a4b266aa",
"lifecycleStage": "POST_TEST_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {}
}
}
```
#### PRE\_PRODUCTION\_TRAFFIC\_SHIFT
このステージは、Amazon ECS が本番トラフィックをグリーンサービスリビジョンにシフトする前に発生します。線形デプロイとカナリアデプロイの場合、このステージはトラフィックシフトの各ステップの前に呼び出されます。
```
{
"executionId": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
"lifecycleStage": "PRE_PRODUCTION_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 0,
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 100
}
}
}
```
#### PRODUCTION\_TRAFFIC\_SHIFT
このステージは、Amazon ECS が本番トラフィックをグリーンサービスリビジョンにシフトさせるときに発生します。`productionTrafficWeights` は、グリーンリビジョンが本番トラフィックを 100% 受信する一方で、ブルーリビジョンは受信しない (0%) ことを示しています。
```
{
"executionId": "f4fcae0f-9bec-41c6-ba87-0eaa0cef8af5",
"lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
}
}
}
```
#### POST\_PRODUCTION\_TRAFFIC\_SHIFT
このステージは、Amazon ECS が本番トラフィックシフトを完了した後に発生します。グリーンサービスリビジョンは、すべての本番トラフィックを処理します。
```
{
"executionId": "5f40ed04-7e54-437d-b95d-98bc872fec49",
"lifecycleStage": "POST_PRODUCTION_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {}
}
}
```
## ロールバック中のライフサイクルフック
専用の `ROLLBACK` ライフサイクルステージはありません。ロールバックが発生すると、Amazon ECS は `PRODUCTION_TRAFFIC_SHIFT` ステージと `TEST_TRAFFIC_SHIFT` ステージ (いずれも反復呼び出しステージ) に登録されたフックを再び呼び出しします。ロールバック中、ペイロードの `productionTrafficWeights` は、ブルーリビジョンに戻るトラフィックを表示します。
`targetServiceRevisionArn` は、本来のデプロイのターゲットであるため、トラフィックがシフトしてもグリーンリビジョン ARN のままです。
次の例は、ロールバック中の `PRODUCTION_TRAFFIC_SHIFT` ペイロードを示しています。グリーンリビジョン (`1920498462936580504`) が本番トラフィックを 100% 受信する一方で、ブルーリビジョン (`9313423515462893900`) は受信しない (0%) 点に注意してください。
```
{
"executionId": "70073435-cb99-457f-b900-6ee1dcad05ec",
"lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
"resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
"executionDetails": {
"serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
"targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
"testTrafficWeights": {},
"productionTrafficWeights": {
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 0,
"arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 100
}
}
}
```
ロールバック中にフックが呼び出されているかどうかを見極めるには、`productionTrafficWeights` を確認します。`targetServiceRevisionArn` (グリーンリビジョン) の重みが 0% で、もう一方のリビジョンの重みが 100% の場合、デプロイはロールバックされます。