(cloudwatch): support AT_LEAST expression in composite alarm rules

[rgoltz]

Describe the feature

The AlarmRule class in aws-cdk-lib/aws-cloudwatch does not support the AT_LEAST function for composite alarm rule expressions.

Since November 2025, CloudWatch supports threshold-based alerting in composite alarms via the AT_LEAST function. This allows a composite alarm to trigger when a minimum number or percentage of child alarms are in a specified state.

The CloudFormation syntax is:

AT_LEAST(threshold, state, (alarm_arn_1, alarm_arn_2, ...))

Where threshold is either an integer (e.g. 2) or a percentage (e.g. 60%), and state is one of ALARM, OK, INSUFFICIENT_DATA, NOT ALARM, NOT OK, or NOT INSUFFICIENT_DATA.

Currently, users must fall back to AlarmRule.fromString() with a hand-crafted expression string to use this feature, losing type safety and ARN resolution.

A previous PR (#36100) attempted to implement this but was closed due to inactivity. Let's have this classic issue/PR pair and push this into the L2 pattern.

Use Case

When monitoring clusters, storage arrays, or microservice fleets, it is common to want alerts only when a critical mass of resources is affected rather than a single one. Examples:

• Alert when at least 2 out of 4 storage volumes are running low on capacity
• Alert when at least 50% of hosts in a cluster show high CPU utilization
• Alert when at least 3 out of 10 microservices report elevated error rates

Without L2 support, users must construct raw rule expression strings, which is error-prone and does not benefit from CDK's token resolution for alarm ARNs.

Proposed Solution

Add two new static methods to AlarmRule and a threshold class:

// Trigger when at least 2 of 3 alarms are in ALARM state
AlarmRule.atLeast(AlarmState.ALARM, {
  operands: [alarm1, alarm2, alarm3],
  threshold: AtLeastThreshold.count(2),
});

// Trigger when at least 60% of alarms are NOT in OK state
AlarmRule.atLeastNot(AlarmState.OK, {
  operands: [alarm1, alarm2, alarm3],
  threshold: AtLeastThreshold.percentage(60),
});

I am planning to submit a PR for this feature.

Other Information

• AWS announcement: https://aws.amazon.com/about-aws/whats-new/2025/11/amazon-cloudwatch-composite-alarms-threshold-based/
• CloudWatch documentation: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Create_Composite_Alarm.html
• Previous PR (closed for staleness): feat(cloudwatch): support AT_LEAST wrapper function of comopsite alarm #36100

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.251.0

AWS CDK CLI version

2.1119.0

Environment details (OS name and version, etc.)

Fedora 43

[rgoltz]

I went ahead and submitted a PR for this: #37693

The implementation builds on the earlier work in #36100 and incorporates all the review feedback that was left there. Unit tests, integration tests, and updated snapshots are included - everything passes locally + in my aws account.

Happy to address any feedback during review!

[pahud]

Thanks for filing this and for submitting PR #37693 — it appears to be a well-structured implementation that builds on the earlier work in #36100 and incorporates the review feedback from @go-to-k and @kumvprat.

I was able to confirm locally that AlarmRule.atLeast and AtLeastThreshold do not exist in aws-cdk-lib@2.251.0.
The fromString() workaround does produce correct CloudFormation output, but as you noted, it lacks type safety and proper ARN resolution. The current AlarmRule class only supports allOf, anyOf, not, fromBoolean, fromAlarm, and fromString:

https://github.com/aws/aws-cdk/blob/818574f2026c4a31f51e7bc03c0079fb9fd76478/packages/aws-cdk-lib/aws-cloudwatch/lib/alarm-rule.ts

In my view, the two-method design (atLeast + atLeastNot) with the AtLeastThreshold abstract class is a clean approach — it avoids the combinatorial explosion of the 6-method design while keeping the API type-safe.

Looking forward to seeing #37693 reviewed and merged!