(aws-ecs): support configurable ECS deployment circuit breaker settings
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
## Describe the feature
Amazon ECS recently added support for configurable deployment circuit breaker settings. The CloudFormation resource specification now includes new `AWS::ECS::Service.DeploymentCircuitBreaker` properties:
- `ResetOnHealthyTask`
- `ThresholdConfiguration`
and a new nested `AWS::ECS::Service.ThresholdConfiguration` property type with:
- `Type`
- `Value`
The CDK `aws-ecs` L2 `DeploymentCircuitBreaker` interface currently only exposes:
```ts
export interface DeploymentCircuitBreaker {
readonly enable?: boolean;
readonly rollback?: boolean;
}
```
`CfnService.DeploymentCircuitBreakerProperty` on current `main` also only includes `enable` and `rollback`, so the generated L1 is stale relative to the latest CloudFormation resource specification.
## Use Case
ECS users need to tune when a rolling deployment is considered failed. The new ECS feature allows users to:
- use a fixed failure count or desired-count percentage as the failure threshold
- choose whether failures are counted consecutively by resetting on a healthy task, or cumulatively across the deployment
This is useful for services with expected startup churn, slow initialization, or different rollback tolerances between development, staging, and production.
## Proposed Solution
Update the generated L1 for `AWS::ECS::Service.DeploymentCircuitBreaker` so `CfnService.DeploymentCircuitBreakerProperty` includes:
```ts
readonly resetOnHealthyTask?: boolean | cdk.IResolvable;
readonly thresholdConfiguration?: CfnService.ThresholdConfigurationProperty | cdk.IResolvable;
```
and add the generated `CfnService.ThresholdConfigurationProperty` with:
```ts
readonly type: string;
readonly value: number;
```
Then add L2 support in `packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts`, for example:
```ts
export interface DeploymentCircuitBreaker {
/**
* Whether to enable the deployment circuit breaker logic.
*
* @default true
*/
readonly enable?: boolean;
/**
* Whether to configure Amazon ECS to roll back the service if a service deployment fails.
*
* @default false
*/
readonly rollback?: boolean;
/**
* Whether the deployment circuit breaker resets its failure count when a task reaches a healthy state.
*
* @default - Amazon ECS default
*/
readonly resetOnHealthyTask?: boolean;
/**
* The failure threshold configuration used by the deployment circuit breaker.
*
* @default - Amazon ECS defaults to BOUNDED_PERCENT with value 50
*/
readonly thresholdConfiguration?: DeploymentCircuitBreakerThresholdConfiguration;
}
```
with a jsii-compatible threshold configuration type, likely something like:
```ts
export interface DeploymentCircuitBreakerThresholdConfiguration {
/**
* How Amazon ECS uses `value` to calculate the failure threshold.
*/
readonly type: DeploymentCircuitBreakerThresholdType;
/**
* The integer Amazon ECS uses to calculate the failure threshold.
*/
readonly value: number;
}
export enum DeploymentCircuitBreakerThresholdType {
COUNT = 'COUNT',
BOUNDED_PERCENT = 'BOUNDED_PERCENT',
UNBOUNDED_PERCENT = 'UNBOUNDED_PERCENT',
}
```
and synthesize:
```ts
deploymentCircuitBreaker: props.circuitBreaker ? {
enable: props.circuitBreaker.enable ?? true,
rollback: props.circuitBreaker.rollback ?? false,
resetOnHealthyTask: props.circuitBreaker.resetOnHealthyTask,
thresholdConfiguration: props.circuitBreaker.thresholdConfiguration,
} : undefined,
```
Unit tests should verify that the new L2 props synthesize to:
```json
{
"DeploymentCircuitBreaker": {
"Enable": true,
"Rollback": true,
"ResetOnHealthyTask": true,
"ThresholdConfiguration": {
"Type": "COUNT",
"Value": 10
}
}
}
```
and that omitting the new optional props preserves the current synthesized output.
## Other Information
AWS announcement:
- https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-ecs-circuit-breaker-settings/
ECS docs:
- https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html
CloudFormation docs:
- https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-ecs-service-deploymentcircuitbreaker.html
- https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-ecs-service-thresholdconfiguration.html
## Acknowledgements
- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change
## AWS CDK Library version
2.261.0
## AWS CDK CLI version
N/A
## Environment details
N/A
Contributor guide
Research direction
Start by inspecting the generated CfnService.DeploymentCircuitBreakerProperty and the L2 types and synthesis logic in packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts. Locate the existing aws-ecs unit tests and verify that the new circuit-breaker properties synthesize correctly while omitting them preserves the current output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- cloud, infrastructure
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100