chore: document reason and mitigation for cross region reference failure from response objects being too large

[colifran]

Issue

#23958, #25114

Reason for this change

Using the crossRegionReference flag on StackProps can produce deployment errors associated with response objects being too large. The root cause of this is a CloudFormation limitation that restricts the total size of a custom resource provider response body to 4096 bytes. Using crossRegionReference will create a custom resource in both the producing stack and the consuming stack. The custom resource provider in the producing stack will respond back to CloudFormation with a response object that includes all exported parameter names and values. Similarly, the consuming stack will respond back to CloudFormation with a response object that includes all imported parameter names and values. The parameter names are created with the following naming format: /cdk/exports/${consumingStackName}/${export-name}. Users need to be careful about stack names and the use of nested stacks to limit the overall length of parameter names which will limit the size of the response body. This PR adds documentation to give more context about this issue and ways to help mitigate it.

Description of changes

Added documentation.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: cc7295c
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[aws-cdk-automation]

Comments on closed issues and PRs are hard for our team to see. If you need help, please open a new issue that references this one.