(hotswap): CLI --hotswap fails with RDS Databases in the stack

[rickstaroO]

Describe the bug

cdk deploy --hotswap is not working when an RDS Database is part of the stack.

Following message occurs in the output:
Could not perform a hotswap deployment, because the CloudFormation template could not be resolved: We don't support attributes of the 'AWS::RDS::DBInstance' resource.

Note: there are no changes to the database inside of the cdk code used. Only the container image was changed.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

Container running with new image after the --hotswap deployment.
RDS Database should be ignored and not touched

Current Behavior

Image was build and uploaded.
cdk deploy --hotswap finishes with errors.
Old container images are still running (no new deployments)

Reproduction Steps

1. Create a stack with ECS Fargate container and a RDS Database inside.
2. Change something in the Dockerfile for the container
3. Run cdk deploy --hotswap

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.223.0

AWS CDK CLI version

2.1032.0

Node.js Version

20.18.3

OS

RHEL 9.4

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hi @rickstaroO,

This appears to be a known limitation of the hotswap feature. The CDK CLI's hotswap deployment fails when it encounters resource attributes from types that aren't yet supported in the CloudFormation template evaluation engine.

The issue occurs because AWS::RDS::DBInstance is not currently in the list of supported resource types for attribute resolution during hotswap evaluation. When your ECS container references the RDS database endpoint (likely via Fn::GetAtt), the hotswap engine cannot evaluate this reference and fails, even though you're only changing the container image.

This is similar to issues with other resource types:

• (hotswap): We don't support attributes of the 'AWS::Logs::LogGroup' resource. aws-cdk#35737 (LogGroup)
• (hotswap): We don't support attributes of the 'AWS::DynamoDB::GlobalTable' resource. aws-cdk#35688 (DynamoDB GlobalTable)
• Elasticache: CDK Hotswap deployment fails with 'We don't support attributes of the AWS::ElastiCache::ReplicationGroup resource' error aws-cdk#35356 (ElastiCache ReplicationGroup)

Workarounds:

1. Use --hotswap-fallback instead of --hotswap:
   bash
   cdk deploy --hotswap-fallback

   This will attempt hotswap but automatically fall back to full deployment without error.

2. Separate your stacks - Deploy RDS in a separate stack and pass the endpoint as a stack property to avoid Fn::GetAtt
   references.

3. Use SSM Parameter Store - Store the RDS endpoint in SSM and use StringParameter.valueFromLookup() instead of direct attribute references.

[pahud]

I think we need a PR to improve the hotswap doc:

Documentation Improvements

1. Add Explicit "Unsupported Resources" Section

After the hotswap supported changes list, add:

markdown

Resources NOT Supported for Fn::GetAtt in Hotswap

When your stack references attributes from unsupported resource types using Fn::GetAtt,
hotswap will fail and fall back to full CloudFormation deployment. Such as:

• AWS::RDS::DBInstance
• AWS::RDS::DBCluster
• AWS::ElastiCache::ReplicationGroup
• AWS::ElastiCache::CacheCluster
• AWS::DynamoDB::GlobalTable (in some contexts)
• AWS::Logs::LogGroup (in some contexts)
• AWS::CloudFormation::Stack (nested stacks)

Workaround: Use --hotswap-fallback to automatically fall back to full deployment,
or restructure your stacks to avoid attribute references from unsupported resources.

For the complete list of supported resources, see the implementation.

2. Improve Clarity

https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk

**⚠ Note aws/aws-cdk#4**: Hotswap has limited support for CloudFormation intrinsic functions:

**Fully Supported:**
- `Ref`
- `Fn::ImportValue`
- `Fn::Join`
- `Fn::Select`
- `Fn::Split`
- `Fn::Sub`

**Partially Supported:**
- `Fn::GetAtt` - Only works for specific resource types. If your stack uses
  `Fn::GetAtt` on unsupported resources (like RDS, ElastiCache, or nested stacks),
  hotswap will fail with an error like:

Could not perform a hotswap deployment, because the CloudFormation template
could not be resolved: We don't support attributes of the 'AWS::RDS::DBInstance' resource.

See supported resources for Fn::GetAtt.

Solution: Use --hotswap-fallback
instead of --hotswap.

3. Add Troubleshooting Section

Add a new section after the hotswap notes:

markdown

Troubleshooting Hotswap Failures

Error: "We don't support attributes of the 'AWS::XXX::YYY' resource"

This means your stack references an unsupported resource type via Fn::GetAtt.

Solutions:

1. Use --hotswap-fallback to automatically fall back to full deployment
2. Separate stacks - move the unsupported resource to a different stack
3. Avoid attribute references - use SSM parameters or hardcoded values instead
4. Contribute support for the resource type to aws-cdk-cli

These changes would make the limitation immediately visible and provide actionable solutions without requiring users to dig through implementation code.