AWS AmazonECS documentation change
Summary
Major restructuring and expansion of deployment lifecycle hooks documentation, including detailed explanations of hookStatus values, hookDetails usage, payload structure, lifecycle stage categories, and rollback behavior. Added practical examples and clarified invocation patterns.
Security assessment
The changes improve documentation clarity and completeness but contain no references to vulnerabilities, security incidents, or explicit security enhancements. The additions focus on functionality like validation tests and governance policies without security-specific context.
Diff
diff --git a/AmazonECS/latest/developerguide/deployment-lifecycle-hooks.md b/AmazonECS/latest/developerguide/deployment-lifecycle-hooks.md index e66e3c9a8..26a56857e 100644 --- a//AmazonECS/latest/developerguide/deployment-lifecycle-hooks.md +++ b//AmazonECS/latest/developerguide/deployment-lifecycle-hooks.md @@ -7 +7 @@ -Lifecycle payloads +Lifecycle hooksLifecycle stage categoriesLifecycle payloadsLifecycle hooks during rollback @@ -11 +11 @@ Lifecycle payloads -When a deployment starts, it goes through lifecycle stages. These stages can be in states such as IN_PROGRESS or successful. You can use lifecycle hooks, which are Lambda functions that Amazon ECS runs on your behalf at specified lifecycle stages. The functions can be either of the following: +When a deployment starts, it progresses through lifecycle stages. Each stage can be in a state such as `IN_PROGRESS` or `SUCCEEDED`. You can use lifecycle hooks, which are Lambda functions that Amazon ECS runs on your behalf at specified lifecycle stages. Each invocation includes a JSON payload with information about the current state of the deployment. @@ -13 +13 @@ When a deployment starts, it goes through lifecycle stages. These stages can be - * An asynchronous API which validates the health check within 15 minutes. +## Lifecycle hooks @@ -15 +15 @@ When a deployment starts, it goes through lifecycle stages. These stages can be - * A poll API which initiates another asynchronous process which evaluates the lifecycle hook completion. +Lifecycle hooks are Lambda functions that Amazon ECS invokes at specific stages of a deployment. You can use hooks to run validation tests, enforce governance policies, or implement manual approval steps before the deployment proceeds. @@ -16,0 +17 @@ When a deployment starts, it goes through lifecycle stages. These stages can be +When Amazon ECS invokes your hook, your function must return a JSON object containing a `hookStatus` field. You can optionally include `callBackDelay` to control retry timing and `hookDetails` to pass data between invocations. If your function doesn't return a valid `hookStatus`, or if it fails, Amazon ECS rolls back the deployment. @@ -17,0 +19 @@ When a deployment starts, it goes through lifecycle stages. These stages can be +### hookStatus values @@ -18,0 +21 @@ When a deployment starts, it goes through lifecycle stages. These stages can be +The following are the valid `hookStatus` values: @@ -20 +23 @@ When a deployment starts, it goes through lifecycle stages. These stages can be -After the function has finished running, it must return a `hookStatus` for the deployment to continue. If a `hookStatus` is not returned, or if the function fails, the deployment rolls back. The following are the `hookStatus` values: + * `SUCCEEDED` – The deployment continues to the next lifecycle stage. @@ -22 +25 @@ After the function has finished running, it must return a `hookStatus` for the d - * `SUCCEEDED` \- the deployment continues to the next lifecycle stage + * `FAILED` – Amazon ECS rolls back the deployment to the last successful service revision. @@ -24 +27 @@ After the function has finished running, it must return a `hookStatus` for the d - * `FAILED` – the deployment rolls back to the last successful deployment. + * `IN_PROGRESS` – Amazon ECS invokes the function again after a delay. By default, the delay is 30 seconds. You can customize this value by returning a `callBackDelay` alongside the `hookStatus`. @@ -26 +28,0 @@ After the function has finished running, it must return a `hookStatus` for the d - * `IN_PROGRESS` – Amazon ECS runs the function again after a short period of time. By default this is a 30 second interval, however this value is customizable by returning a `callBackDelay` alongside the `hookStatus`. @@ -30,2 +32 @@ After the function has finished running, it must return a `hookStatus` for the d - -The following example shows how to return a `hookStatus` with a custom callback delay. In this example, Amazon ECS would retry this hook in 60 seconds instead of the default 30 seconds: +The following example shows how to return a `hookStatus` with a custom callback delay. In this example, Amazon ECS retries the hook after 60 seconds instead of the default 30 seconds: @@ -40,5 +41 @@ The following example shows how to return a `hookStatus` with a custom callback -When a roll back happens, Amazon ECS runs the lifecycle hooks for the following lifecycle stages: - - * PRODUCTION_TRAFFIC_SHIFT - - * TEST_TRAFFIC_SHIFT +### Passing state with hookDetails @@ -45,0 +43 @@ When a roll back happens, Amazon ECS runs the lifecycle hooks for the following +The `hookDetails` field is a dictionary that you can use to pass data into your lifecycle hook function. There are two ways to populate `hookDetails`: @@ -46,0 +45 @@ When a roll back happens, Amazon ECS runs the lifecycle hooks for the following + * **At service creation or update** – Define `hookDetails` in the lifecycle hook configuration within your service definition. Amazon ECS passes this data to your function on every invocation. Use this to make your hooks reusable across multiple services by passing in service-specific configuration. @@ -47,0 +47 @@ When a roll back happens, Amazon ECS runs the lifecycle hooks for the following + * **At runtime via IN_PROGRESS responses** – Return `hookDetails` alongside the `IN_PROGRESS` hook status. Amazon ECS passes this data back to your function on the next invocation. Use this to maintain state between invocations without external storage. @@ -49,5 +48,0 @@ When a roll back happens, Amazon ECS runs the lifecycle hooks for the following -## Lifecycle payloads - -When you configure lifecycle hooks for your ECS service deployments, Amazon ECS invokes these hooks at specific stages of the deployment process. Each lifecycle stage provides a JSON payload with information about the current state of the deployment. This document describes the payload structure for each lifecycle stage. - -### Common payload structure @@ -55 +49,0 @@ When you configure lifecycle hooks for your ECS service deployments, Amazon ECS -All lifecycle stage payloads include the following common fields: @@ -57 +50,0 @@ All lifecycle stage payloads include the following common fields: - * `serviceArn` \- The Amazon Resource Name (ARN) of the service. @@ -59 +52 @@ All lifecycle stage payloads include the following common fields: - * `targetServiceRevisionArn` \- The ARN of the target service revision being deployed. +The following example shows a lifecycle hook configuration in a service definition that passes an S3 bucket name to the function: @@ -61 +53,0 @@ All lifecycle stage payloads include the following common fields: - * `testTrafficWeights` \- A map of service revision ARNs to their corresponding test traffic weight percentages. @@ -63 +55,10 @@ All lifecycle stage payloads include the following common fields: - * `productionTrafficWeights` \- A map of service revision ARNs to their corresponding production traffic weight percentages. + { + "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" + } + } @@ -65,0 +67 @@ All lifecycle stage payloads include the following common fields: +When your function returns `IN_PROGRESS`, you can also include `hookDetails` in the response. Amazon ECS merges this data and passes it back on the next invocation. Common use cases include passing metric counters or ARNs of external resources between invocations. @@ -68 +70,8 @@ All lifecycle stage payloads include the following common fields: -### Lifecycle stage payloads + { + "hookStatus": "IN_PROGRESS", + "callBackDelay": 30, + "hookDetails": { + "approvalChecked": true, + "S3_BUCKET_NAME": "my-approval-bucket" + } + } @@ -70 +78,0 @@ All lifecycle stage payloads include the following common fields: -#### RECONCILE_SERVICE @@ -72 +80 @@ All lifecycle stage payloads include the following common fields: -This stage occurs at the beginning of the deployment process when the service is being reconciled. The following shows an example payload for this lifecycle stage. +On the next invocation, Amazon ECS includes the `hookDetails` in the event payload alongside `executionDetails`: @@ -76,5 +84,8 @@ This stage occurs at the beginning of the deployment process when the service is - "serviceArn": "arn:aws:ecs:us-west-2:1234567890:service/myCluster/myService", - "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892", - "testTrafficWeights": { - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892": 100, - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/78652123": 0 + "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": {} @@ -82,3 +93,3 @@ This stage occurs at the beginning of the deployment process when the service is - "productionTrafficWeights": { - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892": 100, - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/78652123": 0 + "hookDetails": { + "approvalChecked": true, + "S3_BUCKET_NAME": "my-approval-bucket" @@ -89,4 +100 @@ This stage occurs at the beginning of the deployment process when the service is -**Expectations at this stage:** - - * Primary task set is at 0% scale - +Your function can read `event["hookDetails"]` to access the configuration and state from previous invocations. @@ -93,0 +102 @@ This stage occurs at the beginning of the deployment process when the service is +###### Note @@ -94,0 +104 @@ This stage occurs at the beginning of the deployment process when the service is +Data added to `hookDetails` at runtime only persists between invocations of the same hook within a single deployment. Data doesn't carry over between different hooks within the same deployment or the same hook in different deployments. @@ -96,4 +106 @@ This stage occurs at the beginning of the deployment process when the service is -#### PRE_SCALE_UP - -This stage occurs before the new tasks are scaled up. The following shows an example payload for this lifecycle stage. - +## Lifecycle stage categories @@ -101,6 +108 @@ This stage occurs before the new tasks are scaled up. The following shows an exa - { - "serviceArn": "arn:aws:ecs:us-west-2:1234567890:service/myCluster/myService", - "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892", - "testTrafficWeights": {}, - "productionTrafficWeights": {} - } +Lifecycle stages fall into two categories: @@ -107,0 +110 @@ This stage occurs before the new tasks are scaled up. The following shows an exa + 1. **Single invocation stages** – Amazon ECS invokes these stages only once during a service deployment: @@ -109 +112 @@ This stage occurs before the new tasks are scaled up. The following shows an exa -**Expectations at this stage:** + * `RECONCILE_SERVICE` @@ -111 +114 @@ This stage occurs before the new tasks are scaled up. The following shows an exa - * The green service revision tasks are at 0% scale + * `PRE_SCALE_UP` @@ -112,0 +116 @@ This stage occurs before the new tasks are scaled up. The following shows an exa + * `POST_SCALE_UP` @@ -113,0 +118 @@ This stage occurs before the new tasks are scaled up. The following shows an exa + * `POST_TEST_TRAFFIC_SHIFT` @@ -114,0 +120 @@ This stage occurs before the new tasks are scaled up. The following shows an exa + * `POST_PRODUCTION_TRAFFIC_SHIFT` @@ -116 +122 @@ This stage occurs before the new tasks are scaled up. The following shows an exa -#### POST_SCALE_UP + 2. **Recurring invocation stages** – Amazon ECS can invoke these stages multiple times during a service deployment, including during a rollback: @@ -118 +124 @@ This stage occurs before the new tasks are scaled up. The following shows an exa -This stage occurs after the new tasks have been scaled up and are healthy. The following shows an example payload for this lifecycle stage. + * `TEST_TRAFFIC_SHIFT` @@ -119,0 +126 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f + * `PRODUCTION_TRAFFIC_SHIFT` @@ -121,6 +127,0 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f - { - "serviceArn": "arn:aws:ecs:us-west-2:1234567890:service/myCluster/myService", - "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892", - "testTrafficWeights": {}, - "productionTrafficWeights": {} - } @@ -129 +129,0 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f -**Expectations at this stage:** @@ -131 +131 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f - * The green service revision tasks are at 100% scale +## Lifecycle payloads @@ -133 +133 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f - * Tasks in the green service revision are healthy +### Common payload structure @@ -134,0 +135 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f +When Amazon ECS invokes your lifecycle hook Lambda function, the event payload contains the following top-level fields: @@ -135,0 +137 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f + * `executionId` – The unique identifier for this hook execution. @@ -136,0 +139 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f + * `lifecycleStage` – The current lifecycle stage (for example, `PRODUCTION_TRAFFIC_SHIFT`). @@ -138 +141 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f -#### TEST_TRAFFIC_SHIFT + * `resourceArn` – The ARN of the resource associated with the deployment. @@ -140 +143 @@ This stage occurs after the new tasks have been scaled up and are healthy. The f -This stage occurs when test traffic is being shifted to the green service revision tasks. + * `executionDetails` – An object containing the deployment-specific information described in the following list. @@ -142 +144,0 @@ This stage occurs when test traffic is being shifted to the green service revisi -The following shows an example payload for this lifecycle stage. @@ -145,9 +146,0 @@ The following shows an example payload for this lifecycle stage. - { - "serviceArn": "arn:aws:ecs:us-west-2:1234567890:service/myCluster/myService", - "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892", - "testTrafficWeights": { - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/01275892": 100, - "arn:aws:ecs:us-west-2:1234567890:service-revision/myCluster/myService/78652123": 0 - }, - "productionTrafficWeights": {} - }