AWS AmazonECS documentation change
Summary
Enhanced documentation for deployment circuit breaker configuration, adding customization options for failure counting methods (consecutive vs cumulative failures) and threshold types (bounded/unbounded percentage or fixed count). Includes new CLI examples and detailed explanations.
Security assessment
The changes provide operational flexibility for deployment rollback triggers but contain no references to vulnerabilities, exploits, or security incidents. The added configurations (resetOnHealthyTask, thresholdConfiguration) are reliability features for managing deployment failures, not security controls.
Diff
diff --git a/AmazonECS/latest/developerguide/deployment-circuit-breaker.md b/AmazonECS/latest/developerguide/deployment-circuit-breaker.md index d36408505..fe638044a 100644 --- a//AmazonECS/latest/developerguide/deployment-circuit-breaker.md +++ b//AmazonECS/latest/developerguide/deployment-circuit-breaker.md @@ -11 +11 @@ Failure threshold -The deployment circuit breaker is the rolling update mechanism that determines if the tasks reach a steady state. The deployment circuit breaker has an option that will automatically roll back a failed deployment to the deployment that is in the `COMPLETED` state. +The deployment circuit breaker is the rolling update mechanism that determines if the tasks reach a steady state. The deployment circuit breaker has an option that will automatically roll back a failed deployment to the deployment that is in the `COMPLETED` state. You can customize how the circuit breaker counts failures and the threshold at which it triggers, so that rollback behavior matches your application's startup characteristics and your tolerance for task failures. @@ -23 +23 @@ When you create a service, the scheduler keeps track of the tasks that failed to - * Failure - There are consecutive tasks that did not transition to the RUNNING state and the deployment might transition to the FAILED state. + * Failure - By default, consecutive tasks that do not transition to the RUNNING state count toward the failure threshold (`resetOnHealthyTask` is `true`). When `resetOnHealthyTask` is `false`, all task failures accumulate regardless of whether healthy tasks start between failures. @@ -62,0 +63,14 @@ The following `create-service` AWS CLI example shows how to create a Linux servi +The following `create-service` AWS CLI example shows how to create a service with a custom deployment circuit breaker configuration that uses a fixed failure count of 5 and cumulative failure tracking. + + + aws ecs create-service \ + --service-name MyService \ + --deployment-controller type=ECS \ + --desired-count 10 \ + --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true,resetOnHealthyTask=false,thresholdConfiguration={type=COUNT,value=5}}" \ + --task-definition sample-fargate:1 \ + --launch-type FARGATE \ + --platform-family LINUX \ + --platform-version 1.4.0 \ + --network-configuration "awsvpcConfiguration={subnets=[subnet-12344321],securityGroups=[sg-12344321],assignPublicIp=ENABLED}" + @@ -73 +87 @@ Deployment 3 starts and there is no deployment in the `COMPLETED` state, so Depl -The deployment circuit breaker calculates the threshold value, and then uses the value to determine when to move the deployment to a `FAILED` state. +The deployment circuit breaker uses a failure threshold to determine when to move the deployment to a `FAILED` state. You can configure both how failures are counted and the threshold value itself. @@ -75 +89 @@ The deployment circuit breaker calculates the threshold value, and then uses the -The deployment circuit breaker has a minimum threshold of 3 and a maximum threshold of 200. and uses the values in the following formula to determine the deployment failure. +### Failure counting mode @@ -76,0 +91 @@ The deployment circuit breaker has a minimum threshold of 3 and a maximum thresh +The `resetOnHealthyTask` setting controls how the circuit breaker counts task failures during a deployment. @@ -78 +93 @@ The deployment circuit breaker has a minimum threshold of 3 and a maximum thresh - Minimum threshold <= 0.5 * desired task count => maximum threshold +`true` (default) @@ -80 +94,0 @@ The deployment circuit breaker has a minimum threshold of 3 and a maximum thresh -When the result of the calculation is greater than the minimum of 3, but smaller than the maximum of 200, the failure threshold is set to the calculated threshold (rounded up). @@ -82 +96 @@ When the result of the calculation is greater than the minimum of 3, but smaller -###### Note +The failure count resets to 0 each time a task reaches a healthy state. Only consecutive failures count toward the threshold. This mode is useful for applications that might experience intermittent startup failures before stabilizing. @@ -84 +98 @@ When the result of the calculation is greater than the minimum of 3, but smaller -You cannot change either of the threshold values. +`false` @@ -86 +99,0 @@ You cannot change either of the threshold values. -There are two stages for the deployment status check. @@ -88 +101 @@ There are two stages for the deployment status check. - 1. The deployment circuit breaker monitors tasks that are part of the deployment and checks for tasks that are in the `RUNNING` state. The scheduler ignores the failure criteria when a task in the current deployment is in the `RUNNING` state and proceeds to the next stage. When tasks fail to reach in the `RUNNING` state, the deployment circuit breaker increases the failure count by one. When the failure count equals the threshold, the deployment is marked as `FAILED`. +Task failures accumulate throughout the deployment. The failure count never resets, even when healthy tasks start between failures. This mode provides faster detection when any pattern of failures indicates a problematic deployment. @@ -90 +103 @@ There are two stages for the deployment status check. - 2. This stage is entered when there are one or more tasks in the `RUNNING` state. The deployment circuit breaker performs health checks on the following resources for the tasks in the current deployment: +### Threshold configuration @@ -92 +105 @@ There are two stages for the deployment status check. - * Elastic Load Balancing load balancers +The `thresholdConfiguration` setting defines when the circuit breaker triggers. It contains a `type` that determines how the threshold is calculated and a `value` that specifies the percentage or count to use. @@ -94 +107 @@ There are two stages for the deployment status check. - * AWS Cloud Map service +`BOUNDED_PERCENT` (default) @@ -96 +108,0 @@ There are two stages for the deployment status check. - * Amazon ECS container health checks @@ -98 +110,9 @@ There are two stages for the deployment status check. -When a health check fails for the task, the deployment circuit breaker increases the failure count by one. When the failure count equals the threshold, the deployment is marked as `FAILED`. +Amazon ECS multiplies `value` by the latest service desired count to calculate the failure threshold. The result is clamped to a minimum of 3 and a maximum of 200. This is the default type with a default value of 50. + +`UNBOUNDED_PERCENT` + + +Amazon ECS multiplies `value` by the latest service desired count to calculate the failure threshold. There is no minimum or maximum bound on the result. Use this type for services with large desired counts that need a proportional threshold without the 200 cap. + +`COUNT` + @@ -99,0 +120 @@ When a health check fails for the task, the deployment circuit breaker increases +Amazon ECS uses `value` directly as the failure threshold. The threshold remains fixed regardless of the service desired count. Use this type when you want an exact number of tolerated failures, for example, a lower threshold for faster rollbacks in development environments. @@ -100,0 +122 @@ When a health check fails for the task, the deployment circuit breaker increases +For the percentage types (`BOUNDED_PERCENT` and `UNBOUNDED_PERCENT`), the valid range for `value` is 1–100. During a deployment, Amazon ECS continuously uses the latest service desired count in its calculation. @@ -101,0 +124 @@ When a health check fails for the task, the deployment circuit breaker increases +### How `BOUNDED_PERCENT` calculates the threshold @@ -103 +126,8 @@ When a health check fails for the task, the deployment circuit breaker increases -The following table provides some examples. +When you use the default `BOUNDED_PERCENT` threshold type, the deployment circuit breaker calculates the threshold using the following formula. + + + Minimum threshold (3) <= (value/100) * desired task count => Maximum threshold (200) + +When the result of the calculation is less than 3, the threshold is set to 3. When the result is greater than 200, the threshold is set to 200. Otherwise, the threshold is set to the calculated value (rounded up). + +The following table provides examples using the default value of 50. @@ -124 +154 @@ Desired task count | Calculation | Threshold -| 200 +| 200 (the calculated value is greater than the maximum) @@ -131,0 +162,19 @@ Desired task count | Calculation | Threshold +With `UNBOUNDED_PERCENT`, the same calculation applies but without the minimum and maximum bounds. For example, a service with a desired count of 800 and a value of 50 would have a threshold of 400. + +There are two stages for the deployment status check. + + 1. The deployment circuit breaker monitors tasks that are part of the deployment and checks for tasks that are in the `RUNNING` state. The scheduler ignores the failure criteria when a task in the current deployment is in the `RUNNING` state and proceeds to the next stage. When tasks fail to reach the `RUNNING` state, the deployment circuit breaker increases the failure count by one. When the failure count equals the threshold, the deployment is marked as `FAILED`. + + 2. This stage is entered when there are one or more tasks in the `RUNNING` state. The deployment circuit breaker performs health checks on the following resources for the tasks in the current deployment: + + * Elastic Load Balancing load balancers + + * AWS Cloud Map service + + * Amazon ECS container health checks + +When a health check fails for the task, the deployment circuit breaker increases the failure count by one. When the failure count equals the threshold, the deployment is marked as `FAILED`. + + + +