View a markdown version of this page

Amazon ECS サービスデプロイの Lambda フック - Amazon Elastic Container Service
hookStatus 値hookDetails を使用した状態の受け渡しタイムアウト設定サポートされているライフサイクルステージライフサイクルペイロードロールバック中のライフサイクルフック

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 サービスデプロイのライフサイクルフック」を参照してください。

ライフサイクルペイロード

一般的なペイロード構造

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% の場合、デプロイはロールバックされます。