aws-rds: possible regression with global endpoint address

[jmklix]

Describe the bug

There seems to have been a regression with aws-rds. The globalEndpoint has been removed/changed with release v2.180.0.

Regression Issue

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

Last Known Working CDK Version

v2.179.0

Expected Behavior

When trying to use the globalEndpoint you should be able to get the address of it.

Current Behavior

You currently get the following error on version 2.180.0 and above:

Property 'globalEndpoint' does not exist on type 'CfnGlobalCluster'. Did you mean 'attrGlobalEndpoint'?ts(2551)
rds.generated.d.ts(4941, 14): 'attrGlobalEndpoint' is declared here.

Reproduction Steps

run cdk synth on the following minimal project:

import * as cdk from 'aws-cdk-lib';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as r53 from 'aws-cdk-lib/aws-route53';
import type { Construct } from 'constructs';

export class CdkReproStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    //global cluster
    const cfnGlobalCluster = new rds.CfnGlobalCluster(this, 'cfnGlobalCluster', {
      sourceDbClusterIdentifier: new rds.CfnDBCluster(this, 'cfnDBCluster', {
      }).ref,
    });

    //example usage of globalEndpoint
    if (cfnGlobalCluster.globalEndpoint/** <--error is here */ && !cdk.Token.isUnresolved(cfnGlobalCluster.globalEndpoint/** <--error also here */)) {
      new r53.CnameRecord(this, 'cNameRecord', {
        zone: r53.HostedZone.fromHostedZoneAttributes(this, 'hZone', {
          hostedZoneId: 'id',
          zoneName: 'name',
        }),
        recordName: 'globaldb',
        domainName: (cfnGlobalCluster.globalEndpoint/** <--error also here */ as { address: string }).address,
        ttl: cdk.Duration.seconds(5),
      });
    }
  }
}

Possible Solution

No response

Additional Information/Context

No response

CDK CLI Version

2.180.0

Framework Version

No response

Node.js Version

v22.13.1

OS

MacOS Sequoia 15.3.1

Language

TypeScript

Language Version

No response

Other information

No response

[ashishdhingra]

Using above code with aws-cdk-lib version 2.179.0, there was a property named cfnGlobalCluster.globalEndpoint. In aws-cdk-lib version 2.180.0 or later, the property cfnGlobalCluster.globalEndpoint is no longer present. Instead, now there is a property named cfnGlobalCluster.attrGlobalEndpoint.

Looks like in PR #33531, there was a schema change in L1 construct:

├[~] service aws-rds
│ └ resources
│    ├[~]  resource AWS::RDS::DBInstance
│    │  └ properties
│    │     └[+] ApplyImmediately: boolean
│    ├[~]  resource AWS::RDS::DBParameterGroup
│    │  └ properties
│    │     └ Parameters: (documentation changed)
│    └[~]  resource AWS::RDS::GlobalCluster
│       ├ properties
│       │  └[-] GlobalEndpoint: GlobalEndpoint
│       └ attributes
│          └[+] GlobalEndpoint: GlobalEndpoint

The GlobalEndpoint property changed to attribute.

Per AWS::RDS::GlobalCluster, there is no such property called GlobalEndpoint. This appears to be change from CloudFormation side.

[samson-keung]

@ashishdhingra is correct that this was due to a change on the CloudFormation side, in particular, the AWS::RDS::GlobalCluster resource. The change was because GlobalEndpoint isn't supposed to be a resource configuration property but rather, a resource attribute (aka a read-only attribute). Please use attrGlobalEndpoint (and note that it will always be a token as I see that you have a Token.isUnresolved check).

[kellertk]

This change was confusing to us because GlobalEndpoint was documented, but there is no documentation for attrGlobalEndpoint. Further, the CDK release notes are insufficiently detailed for us to know that there was a change to the RDS CFN: the changelogs specify that there was an update the L1 construct definitions, but not which constructs. Is there a better way we can find out about backwards-breaking L1 changes before a failed synth/deploy?

[jmklix]

Is this breaking change going to be documented anywhere? And when will the docs be updated to include attrGlobalEndpoint?

[samson-keung]

@kellertk @jmklix I hear you and I have been following up on this. I have been searching for the team that made the change and brought to their attention that the CFN documentation for the AWS::RDS::GlobalCluster resource is missing the GlobalEndpoint attribute (as that is where CDK read to generate the doc strings for the attribute). I will continue to ask them to update the docs. You can also file a AWS Support ticket to bring more attention to this.

As to the release notes, for the short term, we will call out L1 breaking changes as best as we can. Long term, we are finding ways to auto-catch the breaking changes that CloudFormation resources introduces.

[kellertk]

Hi, @samson-keung

You can also file a AWS Support ticket to bring more attention to this.

Asking customers to reach out to paid support to prioritize a regression in open source software is a bit of an anti-pattern. One reason that CDK is open source is to customers can report issues and collaborate with the team without being having to pay for that privilege.

Also, I'm an AWS employee, so AWS support would direct me to file an internal ticket with the CDK team (or CFN team) instead. If I did that, external customers couldn't benefit from the discussion here.

[SimonCMoore]

This remains with the service team who made the breaking change, RDS team, to resolve internally and is not something we can resolve directly in CDK. Once they have updated the documentation, it will be reflected in CDK in the subsequent release of CDK.

While CDK must respect upstream changes to CloudFormation, including breaking ones as the L1 constructs directly map to the CloudFormation resource, we acknowledge we can do a better job of communicating them when they occur in the release notes and are working on this.