(route53-targets): `@aws-cdk/aws-route53-targets:userPoolDomainNameMethodWithoutCustomResource` feature flag migration is unclear

[blimmer]

Describe the issue

The current documentation for the @aws-cdk/aws-route53-targets:userPoolDomainNameMethodWithoutCustomResource feature flag doesn't provide any information about the migration path from the old default to the new.

From what I can tell, the old Custom Resource just looked up the domain name, which is now exposed through a direct CloudFormation export:

aws-cdk/packages/aws-cdk-lib/aws-cognito/lib/user-pool-domain.ts

Lines 162 to 193 in db62c5f

	/**
	* The domain name of the CloudFront distribution associated with the user pool domain.
	*
	* This method creates a custom resource internally to get the CloudFront domain name.
	*
	* @deprecated use `cloudFrontEndpoint` method instead.
	*/
	public get cloudFrontDomainName(): string {
	if (!this.cloudFrontCustomResource) {
	const sdkCall: AwsSdkCall = {
	service: 'CognitoIdentityServiceProvider',
	action: 'describeUserPoolDomain',
	parameters: {
	Domain: this.domainName,
	},
	physicalResourceId: PhysicalResourceId.of(this.domainName),
	};
	this.cloudFrontCustomResource = new AwsCustomResource(this, 'CloudFrontDomainName', {
	resourceType: 'Custom::UserPoolCloudFrontDomainName',
	onCreate: sdkCall,
	onUpdate: sdkCall,
	policy: AwsCustomResourcePolicy.fromSdkCalls({
	// DescribeUserPoolDomain only supports access level '*'
	// https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncognitouserpools.html#amazoncognitouserpools-actions-as-permissions
	resources: ['*'],
	}),
	// APIs are available in 2.1055.0
	installLatestAwsSdk: false,
	});
	}
	return this.cloudFrontCustomResource.getResponseField('DomainDescription.CloudFrontDistribution');
	}

And the feature flag just changes this reference:

aws-cdk/packages/aws-cdk-lib/aws-route53-targets/lib/userpool-domain.ts

Lines 14 to 23 in db62c5f

	public bind(record: IRecordSet, _zone?: IHostedZone): AliasRecordTargetConfig {
	const dnsName = FeatureFlags.of(record).isEnabled(USER_POOL_DOMAIN_NAME_METHOD_WITHOUT_CUSTOM_RESOURCE)
	? this.domain.cloudFrontEndpoint
	: this.domain.cloudFrontDomainName;
	return {
	dnsName,
	hostedZoneId: CloudFrontTarget.getHostedZoneId(this.domain),
	};
	}
	}

So I'm a bit confused why this is described as a "breaking change" in the docs. I made this update to a few projects of mine and the update of the Route53 record was transparent and didn't cause any downtime or problem.

Could we clarify the documentation to make this sound less scary?

Links

aws-cdk/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md

Lines 1747 to 1762 in db62c5f

	### @aws-cdk/aws-route53-targets:userPoolDomainNameMethodWithoutCustomResource
	*When enabled, use a new method for DNS Name of user pool domain target without creating a custom resource.*
	Flag type: Backwards incompatible bugfix
	When this feature flag is enabled, a new method will be used to get the DNS Name of the user pool domain target. The old method
	creates a custom resource internally, but the new method doesn't need a custom resource.
	If the flag is set to false then a custom resource will be created when using `UserPoolDomainTarget`.
	| Since | Default | Recommended |
	| ----- | ----- | ----- |
	| (not in v1) | | |
	| 2.174.0 | `false` | `true` |

[ykethan]

Hey @blimmer, Thank you for reaching out about the documentation concerns for the @aws-cdk/aws-route53-targets:userPoolDomainNameMethodWithoutCustomResource feature flag. Your feedback is valuable in helping us improve our documentation clarity.

From the PRs that introduced this feature flag (#31402 and #31403) and the code implementation, I've gathered the following details about its behavior:

The feature flag changes how UserPoolDomainTarget gets the CloudFront domain name:
Original implementation: Uses cloudFrontDomainName which creates a custom resource and Lambda function to make an API call to Cognito
New implementation: Uses cloudFrontEndpoint which directly uses CloudFormation's getAtt to get the same information
Both implementations functionally return the same value (CloudFront domain name), but through different mechanisms.

This is currently classified as a "backwards incompatible bugfix" because:

When you enable the flag, the custom resources (Lambda function and custom resource) are removed from your CloudFormation template. If you were to later disable the flag, CloudFormation would need to recreate these resources.
This recreation could potentially cause deployment issues or conflicts, especially if you have other resources depending on them.

I do believe the documentation could be clearer. Here are some improvements we could make by update the feature flag description to explain:

1. Enabling the flag removes the custom resources (Lambda function and Custom::UserPoolCloudFrontDomainName resource) and uses a direct CloudFormation attribute reference instead
2. For most users, enabling the flag will be transparent with no functional change
3. Once enabled, reverting to the old behavior requires recreating resources, which is why it's marked as "backwards
   Add a specific note explaining that while enabling this flag should not cause issues (as you experienced), users should be aware that reverting afterward could be problematic.

Thank you for highlighting this documentation issue.

[blimmer]

Hi @ykethan - thank you for your response

When you enable the flag, the custom resources (Lambda function and custom resource) are removed from your CloudFormation template. If you were to later disable the flag, CloudFormation would need to recreate these resources.
This recreation could potentially cause deployment issues or conflicts, especially if you have other resources depending on them.

I don't quite see how the recreation would cause issues. CDK manages those custom resources, so if any other code was referencing the CR, I would think that it would just be transparently recreated. In fact, during my testing, I switched back and forth between having the flag enabled/disabled and didn't run into any problems. However, there could certainly be some corner case I'm not thinking of.

Agreed with your assessment of how the docs could be improved. My only feedback is clarifying when a revert of the feature flag might be problematic. It honestly all feels pretty safe to me 👍