View a markdown version of this page

Amazon ECS サービスデプロイのライフサイクルフック - Amazon Elastic Container Service
ライフサイクルフックライフサイクルステージのカテゴリライフサイクルペイロードロールバック中のライフサイクルフック

Amazon ECS サービスデプロイのライフサイクルフック

デプロイが開始されると、ライフサイクルステージが進行されます。各ステージは、IN_PROGRESS や SUCCEEDED などの状態になります。指定されたライフサイクルステージで Amazon ECS がユーザーに代わって実行する Lambda 関数のライフサイクルフックを使用できます。各呼び出しには、デプロイの現在の状態に関する情報を含む JSON ペイロードが含まれます。

ライフサイクルフック

ライフサイクルフックは、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 つのデプロイ内の同じフックの呼び出し間でのみ保持されます。データは、同じデプロイ内の異なるフック間や、異なるデプロイ内の同じフック間で引き継がれることはありません。

ライフサイクルステージのカテゴリ

ライフサイクルステージは 2 つのカテゴリに分類されます。

  1. 1 回呼び出しステージ – Amazon ECS はサービスのデプロイ中にこれらのステージを 1 回だけ呼び出します。

    • RECONCILE_SERVICE

    • PRE_SCALE_UP

    • POST_SCALE_UP

    • POST_TEST_TRAFFIC_SHIFT

    • POST_PRODUCTION_TRAFFIC_SHIFT

  2. 反復呼び出しステージ – Amazon ECS は、ロールバック中を含め、サービスのデプロイ中にこれらのステージを複数回呼び出すことができます。

    • TEST_TRAFFIC_SHIFT

    • PRODUCTION_TRAFFIC_SHIFT

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

一般的なペイロード構造

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": {}
  }
}

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