Describe the feature

CloudFormation is introducing breaking changes to drift detection APIs that will affect CDK CLI's drift detection functionality. Action required by August 14, 2025.

Background

CloudFormation team announced changes to drift detection behavior where:

• Resources that fail drift detection (due to permissions/throttling) will return "UNKNOWN" status instead of failing the operation
• Stack drift status will be "UNKNOWN" under certain conditions
• New DriftStatusReason field will provide error details

CFN API Changes:

1. DetectStackResourceDrift API [4] will return resource drift information when CloudFormation is unable to perform drift detection on the resource. The returned information will have a drift status of “UNKNOWN” and a reason under “DriftStatusReason”. Previously, CloudFormation would have failed the DetectStackResourceDrift operation.
2. DescribeStackDriftDetectionStatus API [5] will return a stack drift status of “UNKNOWN” if CloudFormation is unable to perform drift detection on least one resource in the stack AND all other resources are "IN_SYNC". However, if any successfully checked resource is "MODIFIED", the stack drift status will be "DRIFTED", regardless of any incomplete checks.
3. DescribeStackResourceDrifts [6] will include resources with an "UNKNOWN" status, unless otherwise specified. For resources with an "UNKNOWN" status, there will be a field "DriftStatusReason" to explain the reason for the status.

Impact on CDK CLI

CDK CLI depends on CloudFormation drift detection APIs and needs to be updated to handle the new "UNKNOWN" status and associated fields.

Use Case

n/a

Proposed Solution

No response

Other Information

No response

Acknowledgements

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

CDK version used

n/a

Environment details (OS name and version, etc.)

n/a