feat(toolkit-lib): support CloudFormation rollback triggers

[mattmb-aws]

Expose CloudFormation rollback triggers (rollback alarms + monitoring time) so a stack create/update is automatically rolled back when a CloudWatch alarm breaches.

• toolkit-lib: new public rollbackConfiguration deploy option (RollbackConfiguration/RollbackTrigger/RollbackTriggerType). It is validated (<=5 triggers, valid alarm ARNs, 0-180 min) and threaded through to the Create/Update/CreateChangeSet calls, with change detection so an unchanged config does not force a deployment.
• cli: new cdk deploy --rollback-trigger-alarm-arns and --monitoring-time-minutes flags. CLI ARNs default to metric alarms; composite alarms are reachable via the programmatic API.

Follows the same undefined/[]/[...] management semantics as notificationArns.

Fixes aws/aws-cdk#5170

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

Fixes #

Checklist

• This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
  • Release notes for the new version:

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[codecov-commenter]

Codecov Report

❌ Patch coverage is 86.66667% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.08%. Comparing base (7ff50e7) to head (bd51232).

Files with missing lines	Patch %	Lines
packages/aws-cdk/lib/cli/cli.ts	60.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1881      +/-   ##
==========================================
- Coverage   91.10%   91.08%   -0.02%     
==========================================
  Files          80       80              
  Lines       12205    12233      +28     
  Branches     1742     1744       +2     
==========================================
+ Hits        11119    11143      +24     
- Misses       1050     1054       +4     
  Partials       36       36              

Flag	Coverage Δ
suite.unit	91.08% <86.66%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mrgrain]

Design verdict: PASS

• Risk / criticality: medium design risk, critical review depth (blast radius: LARGE — 524 LOC added, touches packages/@aws-cdk/toolkit-lib/lib/api/cloudformation/stack-helpers.ts, import fan-out 12)
• Problem: CDK deploy has no native way to configure CloudFormation rollback triggers (alarm-based auto-rollback on stack create/update), forcing users to manage them out-of-band.
• Why it matters: Users who want automatic rollback safety on deploy — a widely-used CFN feature, tracked upstream as aws/aws-cdk#5170 — currently can't express it through CDK.
• Solution assessment: Mirrors the existing notificationArns pattern end-to-end (interface → validation → threading through toolkit-lib and CLI → change-detection in canSkipDeploy) — low architectural risk, easy to reason about. The one place the mirroring breaks down is the CLI's opt-in condition combined with the undefined-handling asymmetry between notificationArns and rollbackConfiguration — see the 🔴 below.

🔴 Must-fix (1)

--monitoring-time-minutes alone silently clears a stack's existing rollback triggers

File: packages/aws-cdk/lib/cli/cli.ts:442

const rollbackConfiguration = (args.rollbackTriggerAlarmArns !== undefined || args.monitoringTimeMinutes !== undefined)
  ? {
    triggers: (args.rollbackTriggerAlarmArns ?? []).map((arn: string) => ({ arn })),
    monitoringTimeInMinutes: args.monitoringTimeMinutes,
  }
  : undefined;

Passing --monitoring-time-minutes without --rollback-trigger-alarm-arns builds { triggers: [] } — which, per the code's own documented semantics ("{ triggers: [] }: CDK manages it and clears any existing triggers"), is a real management directive, not a no-op. canSkipDeploy only skips the rollback check when rollbackConfiguration === undefined, so this gets forwarded to CloudFormation and wipes any alarms already on the stack.

This directly contradicts the flag's own --help text: "Requires --rollback-trigger-alarm-arns to have any effect."

Consequence: a user runs cdk deploy --monitoring-time-minutes 30 on a stack that already has rollback alarms, intending only to extend the monitoring window — and CloudFormation silently removes all rollback alarms on the next deploy, with no warning, removing an operational safety mechanism that won't be missed until the next incident it should have caught.

Suggestion: gate rollback-management purely on args.rollbackTriggerAlarmArns !== undefined; either ignore a lone --monitoring-time-minutes or throw a ToolkitError telling the user it requires --rollback-trigger-alarm-arns — matching what the help text already claims.

🟡 Should-fix (3)

No test covers --monitoring-time-minutes without --rollback-trigger-alarm-arns

File: packages/aws-cdk/test/commands/deploy.test.ts:431
The new CLI tests cover "ARNs provided" and "no flags" but never the monitoring-time-only combination — exactly the path with the defect above. Add a test once the intended behavior (ignore, or throw) is decided. Add IO Snapshots for these as well.

Help text claims a flag dependency the implementation doesn't enforce

File: packages/aws-cdk/lib/cli/parse-command-line-arguments.ts:507
Same root cause as the 🔴 above, surfacing as a docs/code fidelity gap — the --help text is currently aspirational, not descriptive. Resolves itself once the CLI gating is fixed.

Monitoring time isn't validated as an integer

File: packages/@aws-cdk/toolkit-lib/lib/util/cloudformation.ts:46

const monitoringTime = config.monitoringTimeInMinutes;
if (monitoringTime !== undefined && (monitoringTime < 0 || monitoringTime > MAX_MONITORING_TIME_IN_MINUTES)) {
  throw new ToolkitError(...)
}

Accepts fractional values (e.g. 12.5) and lets NaN through silently (both comparisons are false for NaN). Moves the failure from a clear ToolkitError at the CLI boundary to a murkier CloudFormation API rejection. Suggest adding !Number.isInteger(monitoringTime) to the guard.

Ship summary

Not ready — 1 must-fix: --monitoring-time-minutes alone silently clears a stack's existing rollback triggers, contradicting its own documented behavior. Design is otherwise sound (follows the established notificationArns pattern, proportionate scope, real linked feature request aws/aws-cdk#5170).

---

Created by an AI Agent on behalf of @mrgrain

[mrgrain]

see comment