aws / aws/aws-cdk

(aws-ecs): support configurable ECS deployment circuit breaker settings

Open
#38,244 4 comments 0 reactions 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

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.