aws / aws/aws-cdk

(aws-ecs): Add thresholdConfiguration and resetOnHealthyTask to DeploymentCircuitBreaker

Open
#38,243 2 comments 1 reaction 0 assignees View on GitHub
@aws-cdk/aws-ecs effort/medium feature-request mixins p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

ECS just launched configurable deployment circuit breaker settings (July 1, 2026). The API now supports two new fields on `DeploymentCircuitBreaker`:

- **`resetOnHealthyTask`**: choose between a consecutive model (counter resets when a task becomes healthy) or a cumulative model (failures keep adding up). Defaults to `true`.
- **`thresholdConfiguration`**: set a custom failure threshold as a fixed count or a percentage of desired tasks, instead of being locked to the default `0.5 * desiredCount` formula.

The L2 `DeploymentCircuitBreaker` interface currently only has `enable` and `rollback`, so these new options aren't accessible without escape hatches.

Announcement: [Amazon ECS now supports configurable deployment circuit breaker settings](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-ecs-circuit-breaker-settings/)

### Use Case

We run ECS services where a failed task simply won't recover by retrying. Think misconfigured containers or broken images. In those cases the default circuit breaker threshold just wastes time spinning up tasks that are never going to succeed before it finally triggers a rollback. That blocks the CloudFormation stack update, which in turn blocks the entire CodePipeline. With a lower threshold (or a cumulative counting model) we'd get a faster rollback and unblock the pipeline significantly sooner.

On the flip side, for services with known flaky startup behavior, we'd like to allow more tolerance so they don't roll back prematurely.

Right now the only way to configure this via CDK is through `addPropertyOverride`, which loses type-safety and makes the code harder to read and maintain.

### Proposed Solution

Extend the `DeploymentCircuitBreaker` interface in `packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts`:

```typescript
export interface DeploymentCircuitBreaker {
/** @default true */
readonly enable?: boolean;
/** @default false */
readonly rollback?: boolean;
/**
* Whether the failure counter resets when a task becomes healthy.
* - true: consecutive model (counter resets on healthy task)
* - false: cumulative model (failures accumulate throughout deployment)
* @default true
*/
readonly resetOnHealthyTask?: boolean;
/**
* The threshold configuration for the circuit breaker.
* @default - BOUNDED_PERCENT with value 50
*/
readonly threshold?: CircuitBreakerThreshold;
}

export interface CircuitBreakerThreshold {
/** The type of threshold calculation. */
readonly type: CircuitBreakerThresholdType;
/** The threshold value. */
readonly value: number;
}

export enum CircuitBreakerThresholdType {
/** Use value directly as a fixed failure count */
COUNT = 'COUNT',
/** Multiply value by desired count (bounded between 3 and 200) */
BOUNDED_PERCENT = 'BOUNDED_PERCENT',
/** Multiply value by desired count (unbounded) */
UNBOUNDED_PERCENT = 'UNBOUNDED_PERCENT',
}
```

Then update the CFN rendering in `BaseService` to pass these through.

Regarding input validation: the status API mentions a minimum threshold of 3 and a maximum of 200, but it's unclear whether those are input constraints or just the bounds of the computed result. We'll test what ECS/CloudFormation actually accepts and add appropriate validation in the PR.

### Other Information

- ECS API docs: [DeploymentCircuitBreaker](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeploymentCircuitBreaker.html), [ThresholdConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ThresholdConfiguration.html)
- CloudFormation docs: [DeploymentCircuitBreaker](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-deploymentcircuitbreaker.html), [ThresholdConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-thresholdconfiguration.html)
- Original feature request on the containers roadmap: [aws/containers-roadmap#1247](https://github.com/aws/containers-roadmap/issues/1247)
- Current workaround:
```typescript
const cfnService = service.node.defaultChild as ecs.CfnService;
cfnService.addPropertyOverride(
'DeploymentConfiguration.DeploymentCircuitBreaker.ResetOnHealthyTask', false
);
cfnService.addPropertyOverride(
'DeploymentConfiguration.DeploymentCircuitBreaker.ThresholdConfiguration',
{ Type: 'COUNT', Value: 3 }
);
```
- The L1 type (`CfnService.DeploymentCircuitBreakerProperty`) will likely also need an update once the CloudFormation resource spec catches up.

**Question:**
The `ServiceDeploymentCircuitBreaker` (status/output) docs mention a minimum threshold of 3 and a maximum of 200, but neither the [ECS API](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ThresholdConfiguration.html) nor [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-thresholdconfiguration.html) explicitly document these as input constraints. Has anyone tested what values ECS actually accepts or rejects? Any insights would help us decide what validation to add in the L2.

### Acknowledgements

- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

2.261.0

### AWS CDK CLI version

2.1129.0

### Environment details (OS name and version, etc.)

Linux / Fedora

Contributor guide

Open the contributing guide

Research direction

Start in packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts, where the DeploymentCircuitBreaker interface and BaseService rendering are identified. Read the ECS and CloudFormation ThresholdConfiguration documentation, then inspect the existing L1 CfnService type and related tests if present. Done means the new options are type-safe, rendered through the L2, and validated according to confirmed service constraints.

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
Mostly clear
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.