fix(cloudfront): unstable callerReference in the public key

[pahud]

Summary

• Introduced a feature flag @aws-cdk/aws-cloudfront:stablePublicKeyCallerReference to enable stable caller references for CloudFront PublicKey constructs.
• Updated the PublicKey class to use a stable caller reference when the feature flag is enabled, preventing update failures due to changes in the construct tree.
• Enhanced tests to verify the behavior of the stable caller reference under different scenarios, including feature flag toggling and construct tree changes.
• Updated documentation to reflect the new feature and its usage.

Issue # (if applicable)

Closes #15301.

Reason for this change

CloudFront PublicKey constructs currently use node.addr as the caller reference, which changes when the construct tree structure is modified (e.g., moving constructs, renaming, or refactoring). This causes CloudFormation deployment failures with the error "Invalid request provided: AWS::CloudFront::PublicKey" because CloudFront treats caller reference changes as attempts to create new resources rather than updates.

Description of changes

Core Changes:
• Added feature flag @aws-cdk/aws-cloudfront:stablePublicKeyCallerReference in cx-api/lib/features.ts with recommendedValue: true
• Modified PublicKey class in aws-cloudfront/lib/public-key.ts to:
• Check the feature flag using FeatureFlags.of(this).isEnabled()
• Use Names.uniqueId(this) for stable caller reference when flag is enabled
• Fall back to this.node.addr when flag is disabled (backward compatibility)
• Respect CloudFront's 128-character limit for caller references

Why these changes address the issue:
• Names.uniqueId() generates stable identifiers based on the construct's logical path, which doesn't change when the construct tree is restructured
• Feature flag approach ensures backward compatibility while providing opt-in fix for new projects
• The stable reference prevents CloudFormation from treating updates as resource replacements

Alternatives considered and rejected:
• Always use stable reference: Rejected due to potential breaking changes for existing stacks
• Use physical name: Rejected because it's not always available and may not be unique
• Hash-based approach: Rejected due to complexity and potential collisions

Design decisions:
• Feature flag defaults to true for new projects via recommendedValue
• Maintains backward compatibility by keeping old behavior when flag is disabled
• Uses existing CDK utilities (Names.uniqueId) for consistency with other constructs

Describe any new or updated permissions being added

No new or updated IAM permissions are required. This change only affects the caller reference field in CloudFormation templates, which is a metadata field and doesn't impact AWS API permissions.

Description of how you validated changes

Unit Tests:
• Added comprehensive test suite in aws-cloudfront/test/public-key.test.ts covering:
• Feature flag disabled behavior (backward compatibility)
• Feature flag enabled behavior (stable references)
• Multiple constructs with unique stable references
• CloudFront length limit compliance
• Construct tree changes scenarios
• Behavior differences between flag states

Integration Tests:
• Created integ.public-key-stable-caller-reference.ts demonstrating real-world usage
• Verified CloudFormation template generation with stable caller references
• Tested both flag states to ensure proper behavior

Manual Testing:
• Verified all unit tests pass (10/10 tests passing)
• Confirmed integration test compiles and generates expected snapshots
• Validated that existing PublicKey functionality remains unchanged when flag is disabled

Checklist

• [x] 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

[aws-cdk-automation]

AWS CodeBuild CI Report

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

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